feat: initial project setup

.devcontainer/README.md

@@ -0,0 +1,28 @@
+# Development Container
+
+The development container config ([.devcontainer.json](./devcontainer.json)) enables starting a
+pre-configured [GitHub Codespaces](https://github.com/features/codespaces) environment ready to
+build and preview the docs in this repository.
+
+## Building a preview
+
+The current version of the docs will be automatically built the when a new codespace is created. To
+re-build the docs after making changes, simply run this command from the terminal:
+
+```shell
+make html
+```
+
+Note: you may need go to the main menu, click `View`, then `Terminal` if the terminal isn't visible.
+
+## Viewing the preview
+
+To preview the docs, run the following command in the terminal:
+
+```shell
+python -m http.server 8080 -d _build/html
+```
+
+This will start a simple Python web server on port 8080 in the codespace and open a preview of the
+site in VSCode's built-in simple browser. To preview in your actual browser, click the `PORTS` tab,
+right-click on `Doc Preview (8080)`, and select `Open in Browser`.

.devcontainer/devcontainer.json

@@ -0,0 +1,51 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/ubuntu
+{
+	"name": "Ubuntu",
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	"image": "mcr.microsoft.com/devcontainers/base:jammy",
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	"features": {
+		"ghcr.io/devcontainers/features/github-cli:1": {},
+		"ghcr.io/devcontainers/features/python:1": {}
+	},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	"postCreateCommand": "./.devcontainer/postCreateCommands.sh",
+
+	// Configure tool-specific properties.
+	"customizations": {
+		"codespaces": {
+			"openFiles": [
+				".devcontainer/README.md",
+				"README.md"
+			]
+		},
+		"vscode": {
+			"extensions": [
+				"lextudio.restructuredtext",
+				"trond-snekvik.simple-rst",
+				"DavidAnson.vscode-markdownlint",
+				"ZainChen.json",
+				"stkb.rewrap"
+			]
+		}
+	},
+	"portsAttributes": {
+		"8080": {
+			"label": "Doc Preview",
+			"onAutoForward": "openPreview"
+		}
+	}
+
+	// // Configure command(s) to run after starting
+	// "postStartCommand": {
+	// 	"serve-doc-preview": "python -m http.server 8080 -d _build/html/"
+	// }
+
+	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "root"
+}

.devcontainer/postCreateCommands.sh

@@ -0,0 +1,10 @@
+#/!bin/sh
+
+# Command to run during postCreateCommand
+# Done in script because when done via object the commands are run in parallel
+#  (which isn't always desirable)
+# https://containers.dev/implementors/spec/#parallel-exec
+# https://containers.dev/implementors/json_reference/#formatting-string-vs-array-properties
+
+pip install -r requirements.txt
+make html

.github/workflows/preview-url.yml

@@ -0,0 +1,23 @@
+name: Add preview URL to PR description
+on:
+  pull_request_target:
+    types: [opened]
+    paths:
+      - '**.md'
+      - '**.png'
+      - '**.rst'
+      - '**.svg'
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: edit-pull-request-description
+        uses: Jerome1337/comment-pull-request@v1.0.4
+
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        with:
+          description-message: |
+
+            Preview build: https://dash-docs--${{github.event.pull_request.number}}.org.readthedocs.build/projects/core/en/${{github.event.pull_request.number}}/

.gitignore

@@ -0,0 +1,5 @@
+*.db
+*.exe
+_build
+**/.DS_Store
+.vscode

.markdownlint.json

@@ -0,0 +1,10 @@
+{
+  "default": true,
+  "MD004": { "style": "asterisk"},
+  "MD013": false,
+  "MD033": false,
+  "MD036": false,
+  "MD040": true,
+  "MD041": false,
+  "MD049": true
+}

.readthedocs.yml

@@ -0,0 +1,17 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+build:
+   os: "ubuntu-22.04"
+   tools:
+      python: "3.10"
+
+python:
+   install:
+      - requirements: requirements.txt
+
+formats: [ pdf ]

Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

_static/css/footer.css

@@ -0,0 +1,11 @@
+/* Make each footer item in-line so they stack horizontally instead of vertically */
+.footer-item {
+  display: inline-block;
+}
+
+/* Add a separating border line for all but the last item */
+.footer-item:not(:last-child) {
+  border-right: 1px solid var(--pst-color-text-base);
+  margin-right: .5em;
+  padding-right: .5em;
+}

_static/css/pydata-overrides.css

@@ -0,0 +1,82 @@
+/* Update theme variables based on https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/styling.html#css-theme-variables */
+@import url('https://fonts.googleapis.com/css2?family=Montserrat:ital,wght@0,300;0,400;0,600;0,900;1,900&family=Open+Sans:ital,wght@0,400;0,500;1,400&display=swap');
+
+:root {
+  --dash-blue: #008de4;
+  --dash-deep-blue: #012060;
+  --dash-midnight-blue: #0b0f3b;
+}
+
+html[data-theme="light"] {
+  --pst-color-primary:var(--dash-blue);
+  --pst-color-link:var(--pst-color-primary);
+  --pst-color-link-hover:var(--dash-deep-blue);
+}
+
+html[data-theme="dark"] {
+  --pst-color-primary:var(--dash-blue);
+  --pst-color-link:var(--pst-color-primary);
+}
+
+html {
+  /* Headers */
+  --pst-font-size-h1: 28px;
+  --pst-font-size-h2: 24px;
+  --pst-font-size-h3: 20px;
+
+  /* Sidebar styles */
+  --pst-sidebar-font-size: 0.95em;
+  --pst-sidebar-header-font-size: 1.2em;
+}
+
+html[data-theme=dark] .bd-content img:not(.only-dark):not(.dark-light) {
+    background: none;
+    border-radius: none;
+}
+
+h1,h2,h3,h4,h5,h6{
+  font-family: 'Montserrat', sans-serif;
+  font-weight: 600;
+}
+
+p, a, li, ol {
+  font-family: 'Open Sans', sans-serif;
+} 
+
+p {
+  font-size: 0.95em;
+  line-height: 1.5;
+}
+
+.sidebar-end-items__item {
+    position: relative;
+}
+
+select {
+    width: 100%;
+    padding: 10px;
+    appearance: none;
+    background: transparent;
+    border-radius: 0.25rem;
+}
+
+html[data-theme=dark] select {
+  color: #fff;
+}
+
+html[data-theme="light"] select{
+  color: #000;
+}
+
+html[data-theme="light"] {
+  --table-bg-color-odd: #eeeeee;
+  --table-bg-color-even: #ffffff;
+}
+
+tbody tr:nth-child(odd) { background-color: var(--table-bg-color-odd); }
+tbody tr:nth-child(even) { background-color: var(--table-bg-color-even); }
+
+.table thead th.head {
+  vertical-align: middle;
+}
+