From 805ae5866e288724be21366cead134e532ffae9c Mon Sep 17 00:00:00 2001 From: James Collins Date: Tue, 24 Dec 2024 16:29:37 -0800 Subject: [PATCH 1/3] Add script setup for automatic doc generation --- .../alternative_workflows/build_docs.yml | 21 +++++++++++ .../docs/api_docs.md | 3 -- {{cookiecutter.project_slug}}/mkdocs.yml | 12 +++++-- {{cookiecutter.project_slug}}/pyproject.toml | 6 ++++ .../scripts/gen_ref_pages.py | 35 +++++++++++++++++++ 5 files changed, 71 insertions(+), 6 deletions(-) create mode 100644 {{cookiecutter.project_slug}}/.github/alternative_workflows/build_docs.yml delete mode 100644 {{cookiecutter.project_slug}}/docs/api_docs.md create mode 100644 {{cookiecutter.project_slug}}/scripts/gen_ref_pages.py diff --git a/{{cookiecutter.project_slug}}/.github/alternative_workflows/build_docs.yml b/{{cookiecutter.project_slug}}/.github/alternative_workflows/build_docs.yml new file mode 100644 index 0000000..5c2ecc7 --- /dev/null +++ b/{{cookiecutter.project_slug}}/.github/alternative_workflows/build_docs.yml @@ -0,0 +1,21 @@ +name: Build and Deploy Docs + +on: + workflow_dispatch: + pull_request: + branches: + - main + types: + - closed + +jobs: + build-and-deploy-docs: + if: ${{ github.event.pull_request.merged }} or ${{ github.event_name == 'workflow_dispatch' }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + token: ${{ secrets.GH_TOKEN }} + - uses: ./.github/actions/python-poetry-env + - name: Deploy docs + run: poetry run mkdocs gh-deploy --force \ No newline at end of file diff --git a/{{cookiecutter.project_slug}}/docs/api_docs.md b/{{cookiecutter.project_slug}}/docs/api_docs.md deleted file mode 100644 index 66568b9..0000000 --- a/{{cookiecutter.project_slug}}/docs/api_docs.md +++ /dev/null @@ -1,3 +0,0 @@ -# API documentation - -:::{{ cookiecutter.package_name }} diff --git a/{{cookiecutter.project_slug}}/mkdocs.yml b/{{cookiecutter.project_slug}}/mkdocs.yml index b67c25b..ad5bade 100644 --- a/{{cookiecutter.project_slug}}/mkdocs.yml +++ b/{{cookiecutter.project_slug}}/mkdocs.yml @@ -14,9 +14,9 @@ theme: name: Switch to light mode nav: - - Introduction: 'index.md' - - api_docs.md - - changelog.md + - Home: 'index.md' + - Code Reference: reference/ + - Changelog: changelog.md watch: - src/{{ cookiecutter.package_name }} @@ -61,6 +61,12 @@ markdown_extensions: plugins: - table-reader - search + - gen-files: + scripts: + - scripts/gen_ref_pages.py + - literate-nav: + nav_vile: SUMMARY.md + - section-index - mkdocstrings: default_handler: python handlers: diff --git a/{{cookiecutter.project_slug}}/pyproject.toml b/{{cookiecutter.project_slug}}/pyproject.toml index 76606d7..caaac17 100644 --- a/{{cookiecutter.project_slug}}/pyproject.toml +++ b/{{cookiecutter.project_slug}}/pyproject.toml @@ -37,6 +37,9 @@ click = "*" mkdocstrings = {version = ">=0.23", extras = ["python"]} mkdocs-material = "*" mkdocs-table-reader-plugin = "*" +mkdocs-gen-files = "^0.5.0" +mkdocs-literate-nav = "^0.6.1" +mkdocs-section-index = "^0.3.9" mypy = "*" pre-commit = "*" pymdown-extensions = "*" @@ -78,6 +81,9 @@ ignore = [ "ARG", # "Unused function argument". Fixtures are often unused. "S105", # "Possible hardcoded password". ] +"scripts/**" = [ + "INP001", # "Scripts are not part of a package." +] [tool.ruff.lint.mccabe] max-complexity = 10 diff --git a/{{cookiecutter.project_slug}}/scripts/gen_ref_pages.py b/{{cookiecutter.project_slug}}/scripts/gen_ref_pages.py new file mode 100644 index 0000000..4f9629b --- /dev/null +++ b/{{cookiecutter.project_slug}}/scripts/gen_ref_pages.py @@ -0,0 +1,35 @@ +"""Generate the code reference pages and navigation.""" + +from pathlib import Path + +import mkdocs_gen_files + +nav = mkdocs_gen_files.Nav() # type: ignore[attr-defined, no-untyped-call] + +root = Path(__file__).parent.parent +src = root / "src" + +for path in sorted(src.rglob("*.py")): + module_path = path.relative_to(src).with_suffix("") + doc_path = path.relative_to(src).with_suffix(".md") + full_doc_path = Path("reference", doc_path) + + parts = tuple(module_path.parts) + + if parts[-1] == "__init__": + parts = parts[:-1] + doc_path = doc_path.with_name("index.md") + full_doc_path = full_doc_path.with_name("index.md") + elif parts[-1] == "__main__": + continue + + nav[parts] = doc_path.as_posix() + + with mkdocs_gen_files.open(full_doc_path, "w") as fd: + ident = ".".join(parts) + fd.write(f"::: {ident}") + + mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root)) + +with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file: + nav_file.writelines(nav.build_literate_nav()) \ No newline at end of file From dc52e3f6581a4391ee73db9965a0a8c294cc5348 Mon Sep 17 00:00:00 2001 From: James Collins Date: Tue, 24 Dec 2024 16:31:27 -0800 Subject: [PATCH 2/3] Fix EOL --- .../.github/alternative_workflows/build_docs.yml | 2 +- {{cookiecutter.project_slug}}/scripts/gen_ref_pages.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/{{cookiecutter.project_slug}}/.github/alternative_workflows/build_docs.yml b/{{cookiecutter.project_slug}}/.github/alternative_workflows/build_docs.yml index 5c2ecc7..0a90580 100644 --- a/{{cookiecutter.project_slug}}/.github/alternative_workflows/build_docs.yml +++ b/{{cookiecutter.project_slug}}/.github/alternative_workflows/build_docs.yml @@ -18,4 +18,4 @@ jobs: token: ${{ secrets.GH_TOKEN }} - uses: ./.github/actions/python-poetry-env - name: Deploy docs - run: poetry run mkdocs gh-deploy --force \ No newline at end of file + run: poetry run mkdocs gh-deploy --force diff --git a/{{cookiecutter.project_slug}}/scripts/gen_ref_pages.py b/{{cookiecutter.project_slug}}/scripts/gen_ref_pages.py index 4f9629b..7951f3a 100644 --- a/{{cookiecutter.project_slug}}/scripts/gen_ref_pages.py +++ b/{{cookiecutter.project_slug}}/scripts/gen_ref_pages.py @@ -32,4 +32,4 @@ mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root)) with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file: - nav_file.writelines(nav.build_literate_nav()) \ No newline at end of file + nav_file.writelines(nav.build_literate_nav()) From 28a2aca8b7634467d613da15f69b53a6d62bd8bf Mon Sep 17 00:00:00 2001 From: James Collins Date: Tue, 24 Dec 2024 16:38:05 -0800 Subject: [PATCH 3/3] Raw flags --- .../.github/alternative_workflows/build_docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/{{cookiecutter.project_slug}}/.github/alternative_workflows/build_docs.yml b/{{cookiecutter.project_slug}}/.github/alternative_workflows/build_docs.yml index 0a90580..fcc8fc3 100644 --- a/{{cookiecutter.project_slug}}/.github/alternative_workflows/build_docs.yml +++ b/{{cookiecutter.project_slug}}/.github/alternative_workflows/build_docs.yml @@ -7,7 +7,7 @@ on: - main types: - closed - +{% raw %} jobs: build-and-deploy-docs: if: ${{ github.event.pull_request.merged }} or ${{ github.event_name == 'workflow_dispatch' }} @@ -18,4 +18,4 @@ jobs: token: ${{ secrets.GH_TOKEN }} - uses: ./.github/actions/python-poetry-env - name: Deploy docs - run: poetry run mkdocs gh-deploy --force + run: poetry run mkdocs gh-deploy --force{% endraw %}