Migrate documentation from Sphinx to MkDocs (#579)

Co-authored-by: Dylan H. Morris <dylanhmorris@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

.github/workflows/deptry.yml

@@ -22,7 +22,7 @@ jobs:
             python-version-file: "pyproject.toml"
 
       - name: Install the project
-        run: uv sync --extra dev
+        run: uv sync
 
       - name: run deptry
         run: |

.github/workflows/test.yml

@@ -22,7 +22,7 @@ jobs:
             python-version-file: "pyproject.toml"
 
       - name: Install the project
-        run: uv sync --extra test
+        run: uv sync
 
       - name: run tests
         run: |

.github/workflows/website.yaml

@@ -39,24 +39,18 @@ jobs:
     - name: Install the project
       run: uv sync --all-extras
 
-    - name: Render documentation index from README
-      run: |
-        cp README.md docs/source/index.md
-
     # Building
     - name: Build HTML using uv
       run: |
-        cd docs
-        uv run make tutorials_clean
-        uv run make html
+        uv run make docs
 
     # Upload
     - name: Upload artifacts
       uses: actions/upload-pages-artifact@v4
       with:
         name: github-pages
         retention-days: 7
-        path: docs/build/html/
+        path: site/
 
   deploy:
     # Deploy to the github-pages environment

.pre-commit-config.yaml

@@ -6,20 +6,13 @@ repos:
     hooks:
       - id: check-added-large-files
       - id: check-yaml
+        args: [--unsafe]
       - id: check-toml
       - id: end-of-file-fixer
       - id: mixed-line-ending
       - id: trailing-whitespace
   #####
   # Python
-  - repo: local
-    hooks:
-      - id: generate-md-placeholders
-        name: Tutorials .md placeholders
-        entry: ./hook_scripts/pre-commit-md-placeholder.sh
-        language: script
-        always_run: true
-        files: "docs/source/tutorials/.*(qmd|md)$"
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.13.0
     hooks:
@@ -37,7 +30,7 @@ repos:
     hooks:
       - id: format-qmd-python
         name: Format Python in QMD
-        entry: python hook_scripts/quarto_python_formatter.py "-q --line-length 79"
+        entry: python docs_scripts/quarto_python_formatter.py "-q --line-length 79"
         language: python
         files: \.qmd$
         additional_dependencies: [ruff]

Makefile

@@ -5,12 +5,16 @@ help:
 	@echo "  help           : Show this help message"
 	@echo "  install        : Install the project dependencies"
 	@echo "  test           : Run the tests"
+	@echo "  docs           : Build the documentation"
 
 install:
-	uv sync --extra dev
+	uv sync
 
 test:
 	uv run pytest --mpl --mpl-default-tolerance=10
 
+docs:
+	quarto render docs/tutorials
+	uv run mkdocs build
 
-.PHONY: install test
+.PHONY: install test docs

docs/.gitignore

@@ -1 +1 @@
-build/
+/.quarto/

docs/Makefile

@@ -0,0 +1 @@
+--8<-- "README.md"

docs/README.md

@@ -0,0 +1,10 @@
+document$.subscribe(({ body }) => {
+    renderMathInElement(body, {
+        delimiters: [
+            { left: "$$", right: "$$", display: true },
+            { left: "$", right: "$", display: false },
+            { left: "\\(", right: "\\)", display: false },
+            { left: "\\[", right: "\\]", display: true }
+        ],
+    })
+})