From 536d657473450be0da2a00a103ccb5339c95e7bc Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Wed, 20 Mar 2024 14:44:12 +0000 Subject: [PATCH 01/19] Adding Sphinx docs to template --- pyproject.toml | 4 +- tests/test_package_gen.py | 3 ++ .../docs/_static/.gitignore | 7 ++++ {{cookiecutter.project_slug}}/docs/conf.py | 42 +++++++++++++++++++ {{cookiecutter.project_slug}}/docs/index.md | 10 +++++ {{cookiecutter.project_slug}}/pyproject.toml | 15 +++++++ 6 files changed, 80 insertions(+), 1 deletion(-) create mode 100644 {{cookiecutter.project_slug}}/docs/_static/.gitignore create mode 100644 {{cookiecutter.project_slug}}/docs/conf.py create mode 100644 {{cookiecutter.project_slug}}/docs/index.md diff --git a/pyproject.toml b/pyproject.toml index 28f53260..4cfbcc49 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -20,7 +20,9 @@ lint.ignore = [ "D417", # argument description in docstring (unreliable) "ISC001", # simplify implicit str concatenation (ruff-format recommended) ] -lint.per-file-ignores = {"*tests*" = [ +lint.per-file-ignores = {"*docs/conf.py" = [ + "INP001", +], "*tests*" = [ "INP001", "S101", ], "hooks*" = [ diff --git a/tests/test_package_gen.py b/tests/test_package_gen.py index f0862345..9888e36b 100644 --- a/tests/test_package_gen.py +++ b/tests/test_package_gen.py @@ -56,6 +56,9 @@ def test_package_generation( "tests", pathlib.Path(".github"), pathlib.Path(".github") / "workflows", + pathlib.Path("docs") / "conf.py", + pathlib.Path("docs") / "index.md", + pathlib.Path("docs") / "_static" / ".gitignore", ] for f in expected_files: full_path = test_project_dir / f diff --git a/{{cookiecutter.project_slug}}/docs/_static/.gitignore b/{{cookiecutter.project_slug}}/docs/_static/.gitignore new file mode 100644 index 00000000..436fba7a --- /dev/null +++ b/{{cookiecutter.project_slug}}/docs/_static/.gitignore @@ -0,0 +1,7 @@ +# Workaround to allow tracking empty directory to avoid warning when +# running sphinx-build (source: https://stackoverflow.com/a/932982) + +# Ignore everything in this directory +* +# Except this file +!.gitignore diff --git a/{{cookiecutter.project_slug}}/docs/conf.py b/{{cookiecutter.project_slug}}/docs/conf.py new file mode 100644 index 00000000..33ee0686 --- /dev/null +++ b/{{cookiecutter.project_slug}}/docs/conf.py @@ -0,0 +1,42 @@ +"""Configuration file for the Sphinx documentation builder.""" + +import datetime +from importlib.metadata import version as get_version + +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "{{cookiecutter.package_name}}" +author = "{{cookiecutter.author_given_names}} {{cookiecutter.author_family_names}}" +copyright = f"{datetime.datetime.now(tz=datetime.timezone.utc).year}, {author}" # noqa: A001 +release = get_version("{{cookiecutter.package_name}}") +version = ".".join(release.split(".")[:2]) + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "autodoc2", + "myst_parser", + "sphinx.ext.viewcode", + "sphinx.ext.intersphinx", +] + +intersphinx_mapping = { + "python": ("https://docs.python.org/3/", None), +} + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +autodoc2_packages = ["../src/{{cookiecutter.package_name}}"] +autodoc2_render_plugin = "myst" + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "pydata_sphinx_theme" +html_static_path = ["_static"] diff --git a/{{cookiecutter.project_slug}}/docs/index.md b/{{cookiecutter.project_slug}}/docs/index.md new file mode 100644 index 00000000..0ac6054c --- /dev/null +++ b/{{cookiecutter.project_slug}}/docs/index.md @@ -0,0 +1,10 @@ +# {{cookiecutter.project_name}} + +{{cookiecutter.project_short_description}} + +```{toctree} +--- +maxdepth: 2 +--- +apidocs/index +``` diff --git a/{{cookiecutter.project_slug}}/pyproject.toml b/{{cookiecutter.project_slug}}/pyproject.toml index ce13c8ff..38221e6d 100644 --- a/{{cookiecutter.project_slug}}/pyproject.toml +++ b/{{cookiecutter.project_slug}}/pyproject.toml @@ -33,8 +33,12 @@ name = "{{cookiecutter.project_slug}}" optional-dependencies = {dev = [ "build", "mypy", + "myst-parser", "pre-commit", "ruff", + "sphinx", + "sphinx-autodoc2", + "pydata-sphinx-theme", "tox", "twine", ], test = [ @@ -83,6 +87,8 @@ lint.ignore = [ lint.per-file-ignores = {"tests*" = [ "INP001", "S101", +], "docs/conf.py" = [ + "INP001", ]} lint.select = [ "ALL", @@ -131,4 +137,13 @@ legacy_tox_ini = """ ) %} py3{{python_version}} {%- endfor %} + + [testenv:docs] + commands = + sphinx-build -W -b html docs docs/_build/html + deps = + myst-parser + sphinx + sphinx-autodoc2 + pydata-sphinx-theme """ From aa515236282a968762ab17b59ecaef6c9a029a35 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Wed, 20 Mar 2024 15:06:12 +0000 Subject: [PATCH 02/19] Sorting keys in template pyproject.toml --- {{cookiecutter.project_slug}}/pyproject.toml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/{{cookiecutter.project_slug}}/pyproject.toml b/{{cookiecutter.project_slug}}/pyproject.toml index 38221e6d..f5a256c9 100644 --- a/{{cookiecutter.project_slug}}/pyproject.toml +++ b/{{cookiecutter.project_slug}}/pyproject.toml @@ -84,11 +84,11 @@ lint.ignore = [ "D417", # argument description in docstring (unreliable) "ISC001", # simplify implicit str concatenation (ruff-format recommended) ] -lint.per-file-ignores = {"tests*" = [ +lint.per-file-ignores = {"docs/conf.py" = [ "INP001", - "S101", -], "docs/conf.py" = [ +], "tests*" = [ "INP001", + "S101", ]} lint.select = [ "ALL", From 1b66458fdff7ba8aaebb9e5aa405bf080bd3a2cf Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Wed, 20 Mar 2024 15:12:37 +0000 Subject: [PATCH 03/19] Fix dev dependency sort order in template pyproject.toml --- {{cookiecutter.project_slug}}/pyproject.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/{{cookiecutter.project_slug}}/pyproject.toml b/{{cookiecutter.project_slug}}/pyproject.toml index f5a256c9..da374cdf 100644 --- a/{{cookiecutter.project_slug}}/pyproject.toml +++ b/{{cookiecutter.project_slug}}/pyproject.toml @@ -35,10 +35,10 @@ optional-dependencies = {dev = [ "mypy", "myst-parser", "pre-commit", + "pydata-sphinx-theme", "ruff", "sphinx", "sphinx-autodoc2", - "pydata-sphinx-theme", "tox", "twine", ], test = [ @@ -143,7 +143,7 @@ legacy_tox_ini = """ sphinx-build -W -b html docs docs/_build/html deps = myst-parser + pydata-sphinx-theme sphinx sphinx-autodoc2 - pydata-sphinx-theme """ From ac4323dc35f8d7d1ec5d5a139f856fd84d8b21e2 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Wed, 20 Mar 2024 16:15:43 +0000 Subject: [PATCH 04/19] Add workflow to template to test building documentation --- .../.github/workflows/docs.yml | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 {{cookiecutter.project_slug}}/.github/workflows/docs.yml diff --git a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml new file mode 100644 index 00000000..e804f5e0 --- /dev/null +++ b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml @@ -0,0 +1,42 @@ +name: Documentation + +on: + push: + branches: + - main + pull_request: + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout source + uses: actions/checkout@v4 + - name: Cache tox + uses: actions/cache@v4 + with: + path: .tox + key: tox-${{hashFiles('pyproject.toml')}} + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: "3.x" + cache: "pip" + cache-dependency-path: "pyproject.toml" + - name: Install tox + run: python -m pip install tox + - name: Build HTML documentation with tox + run: tox -e docs + # Uncomment lines below to set-up automatic deployment of documentation to a + # GitHub Pages website on pushing to main - you will need configure the repository + # to deploy from a branch `gh-pages` (https://tinyurl.com/gh-pages-from-branch), + # which will be created the first time this workflow step is run + # - name: Publish documentation on GitHub pages + # if: success() && github.event_name != 'pull_request' + # uses: peaceiris/actions-gh-pages@v3 + # with: + # github_token: ${{ secrets.GITHUB_TOKEN }} + # publish_dir: docs/_build/html + # publish_branch: gh-pages + # user_name: "github-actions[bot]" + # user_email: "github-actions[bot]@users.noreply.github.com" From 37172797bbbb5e010363637fa84f604be3912903 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Wed, 20 Mar 2024 16:16:24 +0000 Subject: [PATCH 05/19] Enable MyST fieldlist extension for defining parameter lists in docstrings --- {{cookiecutter.project_slug}}/docs/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/{{cookiecutter.project_slug}}/docs/conf.py b/{{cookiecutter.project_slug}}/docs/conf.py index 33ee0686..4f703057 100644 --- a/{{cookiecutter.project_slug}}/docs/conf.py +++ b/{{cookiecutter.project_slug}}/docs/conf.py @@ -35,6 +35,8 @@ autodoc2_packages = ["../src/{{cookiecutter.package_name}}"] autodoc2_render_plugin = "myst" +myst_enable_extensions = ["fieldlist"] + # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output From d7ff61fcc784dce4783eff183a4b190ecb4d8656 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Wed, 20 Mar 2024 16:16:52 +0000 Subject: [PATCH 06/19] Add GitHub repository link to generated HTML docs --- {{cookiecutter.project_slug}}/docs/conf.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/{{cookiecutter.project_slug}}/docs/conf.py b/{{cookiecutter.project_slug}}/docs/conf.py index 4f703057..3037d3ff 100644 --- a/{{cookiecutter.project_slug}}/docs/conf.py +++ b/{{cookiecutter.project_slug}}/docs/conf.py @@ -42,3 +42,15 @@ html_theme = "pydata_sphinx_theme" html_static_path = ["_static"] + + +html_theme_options = { + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/", + "icon": "fa-brands fa-square-github", + "type": "fontawesome", + }, + ], +} From 00920e0653ac1e8cb5cd967ce907906d80e4b413 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Wed, 20 Mar 2024 16:17:51 +0000 Subject: [PATCH 07/19] Add documentation badges + build instruction to template README --- {{cookiecutter.project_slug}}/README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/{{cookiecutter.project_slug}}/README.md b/{{cookiecutter.project_slug}}/README.md index 847480f7..b498f2ac 100644 --- a/{{cookiecutter.project_slug}}/README.md +++ b/{{cookiecutter.project_slug}}/README.md @@ -3,6 +3,7 @@ [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit) [![Tests status][tests-badge]][tests-link] [![Linting status][linting-badge]][linting-link] +[![Documentation status][documentation-badge]][linting-link] [![License][license-badge]](./LICENSE.md)