Merge pull request #173 from eshwen/esh-use-mike-docs

Use mike for versioned docs

.github/workflows/api-docs.yml

@@ -11,11 +11,27 @@ concurrency:
 
 jobs:
   docs:
+    runs-on: ubuntu-latest
     permissions:
       contents: 'write'
       actions: 'write'
 
-    uses: eshwen/adrenaline/.github/workflows/[email protected]
-    with:
-      python-version: '3.10'
-      changelog: 'CHANGELOG.md'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: eshwen/adrenaline/[email protected]
+        with:
+          python-version: '3.10'
+          install-dev-deps: true
+
+      - name: Get version number
+        uses: nowsprinting/check-version-format-action@v4
+        id: version
+        with:
+          prefix: 'v'
+
+      - name: Build docs
+        run: |
+          git fetch origin gh-pages --depth=1
+          git config user.name github-actions  # Required for Mike
+          git config user.email [email protected]
+          poetry run mike deploy --update-aliases --push ${{ steps.version.outputs.major_without_prefix }}.${{ steps.version.outputs.minor }} latest

.gitignore

@@ -136,6 +136,3 @@ dmypy.json
 
 # Ruff
 .ruff_cache/
-
-# Auto-generated changelog
-CHANGELOG.md

docs/tooling/documentation.md

@@ -5,23 +5,20 @@ for more information.
 
 ## API documentation
 
-API documentation is built with MkDocs using the Material theme. To build a static copy locally, run
+API documentation is built with MkDocs using the Material theme. The [mike] package wraps MkDocs and allows versioned
+sets of docs to be created. To build a static copy locally and render it live on a local server, run
 
-```shell
-git-changelog -p github -o CHANGELOG.md  # (1)
-mkdocs build
-```
-
-1. This generates the changelog.
+=== "MkDocs standalone"
 
-Then open the homepage HTML file under `site/index.html`.
+    ```shell
+    mkdocs serve
+    ```
 
-Or, to render it live on a local server, run
+=== "MkDocs with mike"
 
-```shell
-git-changelog -p github -o CHANGELOG.md
-mkdocs serve
-```
+    ```shell
+    mike serve
+    ```
 
 For a Sphinx implementation of documentation, see <https://github.com/eshwen/ds-python-boilerplate/releases/tag/v0.1.1>.
 
@@ -59,3 +56,5 @@ TODO: Add extension and plugin descriptions.
 [mkdocstrings]: https://mkdocstrings.github.io/
 
 [gen_ref_pages.py]: https://github.com/eshwen/ds-python-boilerplate/blob/main/docs/gen_ref_pages.py
+
+[mike]: https://github.com/jimporter/mike

mkdocs.yml

@@ -1,4 +1,5 @@
 site_name: My Project
+site_url: https://eshwen.github.io/ds-python-boilerplate/
 repo_url: https://github.com/eshwen/ds-python-boilerplate
 repo_name: eshwen/ds-python-boilerplate
 
@@ -14,12 +15,11 @@ nav:
       - Conda: getting-started/conda.md
       - Development Container: getting-started/dev-container.md
   - Tooling:
-    - Quality: tooling/quality.md
-    - Testing: tooling/testing.md
-    - Documentation: tooling/documentation.md
-    - Pipelines: tooling/pipelines.md
+      - Quality: tooling/quality.md
+      - Testing: tooling/testing.md
+      - Documentation: tooling/documentation.md
+      - Pipelines: tooling/pipelines.md
   - Code Reference: reference/
-  - Changelog: changelog.md
 
 plugins:
   - mkdocstrings:
@@ -43,6 +43,9 @@ plugins:
   - literate-nav:
       nav_file: SUMMARY.md
   - section-index
+  - mike:
+      alias_type: symlink
+      canonical_version: latest
 
 theme:
   name: material
@@ -112,3 +115,5 @@ extra:
     - icon: fontawesome/brands/linkedin
       link: https://www.linkedin.com/in/eshwen-bhal-phd-714557195/
       name: Eshwen Bhal on LinkedIn
+  version:
+    provider: mike

pyproject.toml

@@ -75,7 +75,7 @@ termynal = "^0.11.0"
 mkdocs-gen-files = "^0.5.0"
 mkdocs-literate-nav = "^0.6.1"
 mkdocs-section-index = "^0.3.8"
-git-changelog = "^2.4.0"
+mike = "^2.0.0"
 
 [tool.mypy]
 python_version = "3.10"

requirements-dev.txt

@@ -1,6 +1,5 @@
 annotated-types==0.5.0 ; python_version >= "3.10" and python_version < "3.13"
 anyio==3.7.1 ; python_version >= "3.10" and python_version < "3.13"
-appdirs==1.4.4 ; python_version >= "3.10" and python_version < "3.13"
 appnope==0.1.3 ; python_version >= "3.10" and python_version < "3.13" and (platform_system == "Darwin" or sys_platform == "darwin")
 argon2-cffi-bindings==21.2.0 ; python_version >= "3.10" and python_version < "3.13"
 argon2-cffi==23.1.0 ; python_version >= "3.10" and python_version < "3.13"
@@ -31,10 +30,11 @@ fastjsonschema==2.18.0 ; python_version >= "3.10" and python_version < "3.13"
 filelock==3.12.2 ; python_version >= "3.10" and python_version < "3.13"
 fqdn==1.5.1 ; python_version >= "3.10" and python_version < "3.13"
 ghp-import==2.1.0 ; python_version >= "3.10" and python_version < "3.13"
-git-changelog==2.4.0 ; python_version >= "3.10" and python_version < "3.13"
 griffe==0.35.0 ; python_version >= "3.10" and python_version < "3.13"
 identify==2.5.27 ; python_version >= "3.10" and python_version < "3.13"
 idna==3.4 ; python_version >= "3.10" and python_version < "3.13"
+importlib-metadata==7.0.1 ; python_version >= "3.10" and python_version < "3.13"
+importlib-resources==6.1.1 ; python_version >= "3.10" and python_version < "3.13"
 iniconfig==2.0.0 ; python_version >= "3.10" and python_version < "3.13"
 ipykernel==6.25.1 ; python_version >= "3.10" and python_version < "3.13"
 ipython-genutils==0.2.0 ; python_version >= "3.10" and python_version < "3.13"
@@ -65,6 +65,7 @@ markdown==3.4.4 ; python_version >= "3.10" and python_version < "3.13"
 markupsafe==2.1.3 ; python_version >= "3.10" and python_version < "3.13"
 matplotlib-inline==0.1.6 ; python_version >= "3.10" and python_version < "3.13"
 mergedeep==1.3.4 ; python_version >= "3.10" and python_version < "3.13"
+mike==2.0.0 ; python_version >= "3.10" and python_version < "3.13"
 mistune==3.0.1 ; python_version >= "3.10" and python_version < "3.13"
 mkdocs-autorefs==0.5.0 ; python_version >= "3.10" and python_version < "3.13"
 mkdocs-gen-files==0.5.0 ; python_version >= "3.10" and python_version < "3.13"
@@ -112,6 +113,7 @@ pydantic-core==2.6.3 ; python_version >= "3.10" and python_version < "3.13"
 pydantic==2.3.0 ; python_version >= "3.10" and python_version < "3.13"
 pygments==2.16.1 ; python_version >= "3.10" and python_version < "3.13"
 pymdown-extensions==10.4 ; python_version >= "3.10" and python_version < "3.13"
+pyparsing==3.0.9 ; python_version >= "3.10" and python_version < "3.13"
 pytest-asyncio==0.21.1 ; python_version >= "3.10" and python_version < "3.13"
 pytest-cov==4.1.0 ; python_version >= "3.10" and python_version < "3.13"
 pytest-mock==3.11.1 ; python_version >= "3.10" and python_version < "3.13"
@@ -133,7 +135,6 @@ rfc3339-validator==0.1.4 ; python_version >= "3.10" and python_version < "3.13"
 rfc3986-validator==0.1.1 ; python_version >= "3.10" and python_version < "3.13"
 rpds-py==0.9.2 ; python_version >= "3.10" and python_version < "3.13"
 ruff==0.1.15 ; python_version >= "3.10" and python_version < "3.13"
-semver==3.0.2 ; python_version >= "3.10" and python_version < "3.13"
 send2trash==1.8.2 ; python_version >= "3.10" and python_version < "3.13"
 setuptools==68.1.2 ; python_version >= "3.10" and python_version < "3.13"
 six==1.16.0 ; python_version >= "3.10" and python_version < "3.13"
@@ -153,6 +154,7 @@ typing-inspect==0.9.0 ; python_version >= "3.10" and python_version < "3.13"
 tzdata==2023.3 ; python_version >= "3.10" and python_version < "3.13"
 uri-template==1.3.0 ; python_version >= "3.10" and python_version < "3.13"
 urllib3==2.0.7 ; python_version >= "3.10" and python_version < "3.13"
+verspec==0.1.0 ; python_version >= "3.10" and python_version < "3.13"
 virtualenv==20.24.3 ; python_version >= "3.10" and python_version < "3.13"
 voila==0.5.5 ; python_version >= "3.10" and python_version < "3.13"
 watchdog==3.0.0 ; python_version >= "3.10" and python_version < "3.13"
@@ -163,3 +165,4 @@ websocket-client==1.6.2 ; python_version >= "3.10" and python_version < "3.13"
 websockets==11.0.3 ; python_version >= "3.10" and python_version < "3.13"
 widgetsnbextension==4.0.8 ; python_version >= "3.10" and python_version < "3.13"
 wrapt==1.15.0 ; python_version >= "3.10" and python_version < "3.13"
+zipp==3.17.0 ; python_version >= "3.10" and python_version < "3.13"