diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 00000000..9b944077 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,36 @@ +--- +name: Publish Develop Docs + +on: + push: + branches: + - main + +permissions: + contents: write + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Setting up PDM + uses: pdm-project/setup-pdm@v4 + with: + python-version: "3.10" + architecture: x64 + - name: Setting up nox + uses: wntrblm/nox@2024.03.02 + with: + python-versions: "3.10" + - name: Configure Git Credentials + run: | + git config user.email "action@github.com" + git config user.name "GitHub Action" + - name: Build Documentation + run: | + git fetch origin gh-pages:gh-pages + nox -s docs -- deploy --update-aliases dev + git push origin gh-pages diff --git a/mkdocs.yml b/mkdocs.yml index e50464e5..81293893 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -27,6 +27,7 @@ theme: name: Switch to dark mode plugins: search: null + mike: null mkdocstrings: handlers: python: @@ -42,6 +43,12 @@ plugins: show_root_heading: true filters: - '!^_' +extra: + version: + provider: mike + default: + - latest + - dev markdown_extensions: - toc: toc_depth: 2 diff --git a/noxfile.py b/noxfile.py index 5abaa217..2a60bada 100644 --- a/noxfile.py +++ b/noxfile.py @@ -139,6 +139,14 @@ def bump(session: nox.Session) -> None: session.run("pdm", "bump", *session.posargs, external=True) +@nox.session +def docs(session: nox.Session) -> None: + """Builds and deploys the code documentation.""" + args = session.posargs or [] + session.run_always("pdm", "install", "--group", "docs", external=True) + session.run("pdm", "run", "mike", *args) + + @nox.session def build(session: nox.Session) -> None: """Builds the source and wheel distributions.""" diff --git a/pdm.lock b/pdm.lock index 0e533170..8dc4367f 100644 --- a/pdm.lock +++ b/pdm.lock @@ -5,7 +5,7 @@ groups = ["default", "dev", "docs", "all", "typecheck", "lint", "vision", "test"] strategy = ["cross_platform", "inherit_metadata"] lock_version = "4.4.1" -content_hash = "sha256:9cbea3dbe7c6b035b427d2b3c93b153739d89ce71b182800a17bf4441e17e436" +content_hash = "sha256:4f1bba07786b708fe7be9ff1c02c816a26da0556ab6f29352786ce4f468501df" [[package]] name = "absl-py" @@ -667,6 +667,31 @@ files = [ {file = "idna-3.6.tar.gz", hash = "sha256:9ecdbbd083b06798ae1e86adcbfe8ab1479cf864e4ee30fe4e46a003d12491ca"}, ] +[[package]] +name = "importlib-metadata" +version = "7.0.2" +requires_python = ">=3.8" +summary = "Read metadata from Python packages" +groups = ["dev", "docs"] +dependencies = [ + "zipp>=0.5", +] +files = [ + {file = "importlib_metadata-7.0.2-py3-none-any.whl", hash = "sha256:f4bc4c0c070c490abf4ce96d715f68e95923320370efb66143df00199bb6c100"}, + {file = "importlib_metadata-7.0.2.tar.gz", hash = "sha256:198f568f3230878cb1b44fbd7975f87906c22336dba2e4a7f05278c281fbd792"}, +] + +[[package]] +name = "importlib-resources" +version = "6.3.2" +requires_python = ">=3.8" +summary = "Read resources from Python packages" +groups = ["dev", "docs"] +files = [ + {file = "importlib_resources-6.3.2-py3-none-any.whl", hash = "sha256:f41f4098b16cd140a97d256137cfd943d958219007990b2afb00439fc623f580"}, + {file = "importlib_resources-6.3.2.tar.gz", hash = "sha256:963eb79649252b0160c1afcfe5a1d3fe3ad66edd0a8b114beacffb70c0674223"}, +] + [[package]] name = "iniconfig" version = "2.0.0" @@ -798,6 +823,20 @@ files = [ {file = "Markdown-3.5.2.tar.gz", hash = "sha256:e1ac7b3dc550ee80e602e71c1d168002f062e49f1b11e26a36264dafd4df2ef8"}, ] +[[package]] +name = "markdown-exec" +version = "1.8.0" +requires_python = ">=3.8" +summary = "Utilities to execute code blocks in Markdown files." +groups = ["dev", "docs"] +dependencies = [ + "pymdown-extensions>=9", +] +files = [ + {file = "markdown_exec-1.8.0-py3-none-any.whl", hash = "sha256:e80cb766eff8d0bcd1cdd133dba58223b42edbd1b7b9672481c2189572401bff"}, + {file = "markdown_exec-1.8.0.tar.gz", hash = "sha256:0a932312f0ca89b82150e1638e84febb90eadd410dfd2417f05759c06deed727"}, +] + [[package]] name = "markdown-it-py" version = "3.0.0" @@ -874,6 +913,25 @@ files = [ {file = "mergedeep-1.3.4.tar.gz", hash = "sha256:0096d52e9dad9939c3d975a774666af186eda617e6ca84df4c94dec30004f2a8"}, ] +[[package]] +name = "mike" +version = "2.0.0" +summary = "Manage multiple versions of your MkDocs-powered documentation" +groups = ["dev", "docs"] +dependencies = [ + "importlib-metadata", + "importlib-resources", + "jinja2>=2.7", + "mkdocs>=1.0", + "pyparsing>=3.0", + "pyyaml>=5.1", + "verspec", +] +files = [ + {file = "mike-2.0.0-py3-none-any.whl", hash = "sha256:87f496a65900f93ba92d72940242b65c86f3f2f82871bc60ebdcffc91fad1d9e"}, + {file = "mike-2.0.0.tar.gz", hash = "sha256:566f1cab1a58cc50b106fb79ea2f1f56e7bfc8b25a051e95e6eaee9fba0922de"}, +] + [[package]] name = "mkdocs" version = "1.5.3" @@ -951,6 +1009,30 @@ files = [ {file = "mkdocs_material_extensions-1.3.1.tar.gz", hash = "sha256:10c9511cea88f568257f960358a467d12b970e1f7b2c0e5fb2bb48cab1928443"}, ] +[[package]] +name = "mkdocs-redirects" +version = "1.2.1" +requires_python = ">=3.6" +summary = "A MkDocs plugin for dynamic page redirects to prevent broken links." +groups = ["dev", "docs"] +dependencies = [ + "mkdocs>=1.1.1", +] +files = [ + {file = "mkdocs-redirects-1.2.1.tar.gz", hash = "sha256:9420066d70e2a6bb357adf86e67023dcdca1857f97f07c7fe450f8f1fb42f861"}, +] + +[[package]] +name = "mkdocs-version-annotations" +version = "1.0.0" +requires_python = ">=3.7,<4.0" +summary = "MkDocs plugin to add custom admonitions for documenting version differences" +groups = ["dev", "docs"] +files = [ + {file = "mkdocs-version-annotations-1.0.0.tar.gz", hash = "sha256:6786024b37d27b330fda240b76ebec8e7ce48bd5a9d7a66e99804559d088dffa"}, + {file = "mkdocs_version_annotations-1.0.0-py3-none-any.whl", hash = "sha256:385004eb4a7530dd87a227e08cd907ce7a8fe21fdf297720a4149c511bcf05f5"}, +] + [[package]] name = "mkdocstrings" version = "0.24.1" @@ -1628,6 +1710,17 @@ files = [ {file = "pymdown_extensions-10.7.1.tar.gz", hash = "sha256:c70e146bdd83c744ffc766b4671999796aba18842b268510a329f7f64700d584"}, ] +[[package]] +name = "pyparsing" +version = "3.1.2" +requires_python = ">=3.6.8" +summary = "pyparsing module - Classes and methods to define and execute parsing grammars" +groups = ["dev", "docs"] +files = [ + {file = "pyparsing-3.1.2-py3-none-any.whl", hash = "sha256:f9db75911801ed778fe61bb643079ff86601aca99fcae6345aa67292038fb742"}, + {file = "pyparsing-3.1.2.tar.gz", hash = "sha256:a1bac0ce561155ecc3ed78ca94d3c9378656ad4c94c1270de543f621420f94ad"}, +] + [[package]] name = "pyreadline3" version = "3.4.1" @@ -1982,7 +2075,7 @@ name = "setuptools" version = "69.2.0" requires_python = ">=3.8" summary = "Easily download, build, install, upgrade, and uninstall Python packages" -groups = ["default", "dev", "typecheck"] +groups = ["default", "dev", "docs", "typecheck"] files = [ {file = "setuptools-69.2.0-py3-none-any.whl", hash = "sha256:c21c49fb1042386df081cb5d86759792ab89efca84cf114889191cd09aacc80c"}, {file = "setuptools-69.2.0.tar.gz", hash = "sha256:0ff4183f8f42cd8fa3acea16c45205521a4ef28f73c6391d8a25e92893134f2e"}, @@ -2362,6 +2455,16 @@ files = [ {file = "urllib3-2.2.1.tar.gz", hash = "sha256:d0570876c61ab9e520d776c38acbbb5b05a776d3f9ff98a5c8fd5162a444cf19"}, ] +[[package]] +name = "verspec" +version = "0.1.0" +summary = "Flexible version handling" +groups = ["dev", "docs"] +files = [ + {file = "verspec-0.1.0-py3-none-any.whl", hash = "sha256:741877d5633cc9464c45a469ae2a31e801e6dbbaa85b9675d481cda100f11c31"}, + {file = "verspec-0.1.0.tar.gz", hash = "sha256:c4504ca697b2056cdb4bfa7121461f5a0e81809255b41c03dda4ba823637c01e"}, +] + [[package]] name = "virtualenv" version = "20.25.1" @@ -2510,3 +2613,14 @@ files = [ {file = "yarl-1.9.4-py3-none-any.whl", hash = "sha256:928cecb0ef9d5a7946eb6ff58417ad2fe9375762382f1bf5c55e61645f2c43ad"}, {file = "yarl-1.9.4.tar.gz", hash = "sha256:566db86717cf8080b99b58b083b773a908ae40f06681e87e589a976faf8246bf"}, ] + +[[package]] +name = "zipp" +version = "3.18.1" +requires_python = ">=3.8" +summary = "Backport of pathlib-compatible object wrapper for zip files" +groups = ["dev", "docs"] +files = [ + {file = "zipp-3.18.1-py3-none-any.whl", hash = "sha256:206f5a15f2af3dbaee80769fb7dc6f249695e940acca08dfb2a4769fe61e538b"}, + {file = "zipp-3.18.1.tar.gz", hash = "sha256:2884ed22e7d8961de1c9a05142eb69a247f120291bc0206a00a7642f09b5b715"}, +] diff --git a/pyproject.toml b/pyproject.toml index 67bdc37e..2149c1c4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -84,8 +84,13 @@ test = [ ] docs = [ "mkdocs>=1.5.3", - "mkdocstrings[python]>=0.24.0", "mkdocs-material>=9.5.6", + "mkdocstrings[python]>=0.24.0", + "mike>=2.0.0", + "setuptools>=62.3.3", + "markdown-exec>=0.7.0", + "mkdocs-redirects>=1.2.0", + "mkdocs-version-annotations>=1.0.0", ] dev = [ "isort>=5.12.0", @@ -100,8 +105,13 @@ dev = [ "pytest>=7.2.2", "pytest-cov>=4.1.0", "mkdocs>=1.5.3", - "mkdocstrings[python]>=0.24.0", "mkdocs-material>=9.5.6", + "mkdocstrings[python]>=0.24.0", + "mike>=2.0.0", + "setuptools>=62.3.3", + "markdown-exec>=0.7.0", + "mkdocs-redirects>=1.2.0", + "mkdocs-version-annotations>=1.0.0", ] [tool.isort]