Merge pull request #30 from kraken-tech/docs

Add mkdocs with material theme, built to github pages using Mike

Author: meshy

.github/workflows/update-dev-docs.yml

@@ -0,0 +1,27 @@
+name: build main branch docs
+on:
+  push:
+    branches:
+      - main
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.13
+      - name: Install Dependencies
+        run: |
+          pip install --group docs
+      - name: Configure git
+        run: |
+          git config --global user.name "GitHub docs action"
+          git config --global user.email "django-subatomic+docs@example.com"
+      - name: Build Docs Site
+        run: |
+          mike deploy --push --update-aliases dev

.github/workflows/update-docs.yml

@@ -0,0 +1,27 @@
+name: build release docs
+on:
+  release:
+    types: [published]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.13
+      - name: Install Dependencies
+        run: |
+          pip install --group docs
+      - name: Configure git
+        run: |
+          git config --global user.name "GitHub docs action"
+          git config --global user.email "django-subatomic+docs@example.com"
+      - name: Build Docs Site
+        run: |
+          mike deploy --push --update-aliases ${{ github.event.release.tag_name }} latest
+          mike set-default latest --push

CONTRIBUTING.md

@@ -89,5 +89,34 @@ Python dependencies are declared in `pyproject.toml`.
 - _package_ dependencies in the `dependencies` array in the `[project]` section.
 - _development_ dependencies in the `[dependency-groups]` section.
 
-[semver]: https://semver.org/
+## Docs
+
+Our documentation lives in the `docs/` directory.
+It is written in Markdown, and built with [MkDocs].
+We use the [Material for MkDocs] theme.
+Every time we merge or make a release,
+a GitHub Action runs [Mike],
+which commits a new version of the docs to the `gh-pages` branch
+so that it is deployed to [GitHub Pages].
+
+To build the docs locally, you will need the "docs" dependency-group installed
+(if you have already installed the "dev" group, you can skip this):
+
+```
+pip install --group docs
+```
+
+Once you have the dependencies installed,
+you can serve the docs locally with:
+
+```
+mkdocs serve
+```
+
+
+[GitHub Pages]: https://pages.github.com/
+[Material for MkDocs]: https://squidfunk.github.io/mkdocs-material/
+[Mike]: https://github.com/jimporter/mike
+[MkDocs]: https://www.mkdocs.org/
 [keepachangelog]: https://keepachangelog.com/
+[semver]: https://semver.org/

docs/index.md

@@ -0,0 +1 @@
+# Subatomic docs

mkdocs.yml

@@ -0,0 +1,13 @@
+site_name: Django-subatomic docs
+repo_name: kraken-tech/django-subatomic
+repo_url: https://github.com/kraken-tech/django-subatomic
+theme:
+  name: material
+extra:
+  version:
+    provider: mike
+    alias: true
+    default:
+      - latest
+plugins:
+  - mike

pyproject.toml

@@ -62,11 +62,16 @@ default-groups = []
 
 [dependency-groups]
 dev = [
+    {include-group = "docs"},
     {include-group = "mypy"},
     {include-group = "test_runners"},
     {include-group = "python_tests"},
     "pre-commit",
 ]
+docs = [
+    "mike",
+    "mkdocs-material",
+]
 mypy = [
     {include-group = "python_tests"},
     "django-stubs[compatible-mypy]",