From a5f0d52a069cabbb62450e1f88b6b18509220d73 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Wed, 20 Mar 2024 19:12:41 +0000 Subject: [PATCH 01/24] Adding MkDocs docs to template --- tests/test_package_gen.py | 3 ++ .../.github/workflows/docs.yml | 42 +++++++++++++++++++ {{cookiecutter.project_slug}}/README.md | 21 ++++++++++ {{cookiecutter.project_slug}}/docs/api.md | 3 ++ {{cookiecutter.project_slug}}/docs/index.md | 3 ++ {{cookiecutter.project_slug}}/mkdocs.yml | 41 ++++++++++++++++++ {{cookiecutter.project_slug}}/pyproject.toml | 13 ++++++ .../{{cookiecutter.package_name}}/__init__.py | 14 +++++++ 8 files changed, 140 insertions(+) create mode 100644 {{cookiecutter.project_slug}}/.github/workflows/docs.yml create mode 100644 {{cookiecutter.project_slug}}/docs/api.md create mode 100644 {{cookiecutter.project_slug}}/docs/index.md create mode 100644 {{cookiecutter.project_slug}}/mkdocs.yml diff --git a/tests/test_package_gen.py b/tests/test_package_gen.py index f0862345..7d4d8516 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", + "mkdocs.yml", + pathlib.Path("docs") / "index.md", + pathlib.Path("docs") / "api.md", ] for f in expected_files: full_path = test_project_dir / f diff --git a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml new file mode 100644 index 00000000..e8160daf --- /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: site + # publish_branch: gh-pages + # user_name: "github-actions[bot]" + # user_email: "github-actions[bot]@users.noreply.github.com" diff --git a/{{cookiecutter.project_slug}}/README.md b/{{cookiecutter.project_slug}}/README.md index 847480f7..b1519e0d 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) -[Framework 1](https://something.com) -[Framework 2](https://something.com) -[Framework 3](https://something.com) +- [Framework 1](https://something.com) +- [Framework 2](https://something.com) +- [Framework 3](https://something.com) ## Getting Started From 788c9f733b1d2e7c62737115a68d5457cd68a5b9 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Thu, 21 Mar 2024 08:38:25 +0000 Subject: [PATCH 06/24] Add edit URI for GitHub links --- {{cookiecutter.project_slug}}/mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/{{cookiecutter.project_slug}}/mkdocs.yml b/{{cookiecutter.project_slug}}/mkdocs.yml index 7d9d9a39..a620c4b3 100644 --- a/{{cookiecutter.project_slug}}/mkdocs.yml +++ b/{{cookiecutter.project_slug}}/mkdocs.yml @@ -4,6 +4,7 @@ site_author: "{{cookiecutter.author_given_names}} {{cookiecutter.author_family_n copyright: "© {% now 'utc', '%Y' %}, {{cookiecutter.author_given_names}} {{cookiecutter.author_family_names}}" repo_url: "https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/" repo_name: "{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}" +edit_uri: edit/main/docs/ theme: name: "material" From ebebf8528c1ff68f85440e7b4a824e758d7ea244 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Thu, 21 Mar 2024 08:38:41 +0000 Subject: [PATCH 07/24] Use MkDocs recommended stricter validation --- {{cookiecutter.project_slug}}/mkdocs.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/{{cookiecutter.project_slug}}/mkdocs.yml b/{{cookiecutter.project_slug}}/mkdocs.yml index a620c4b3..bf555372 100644 --- a/{{cookiecutter.project_slug}}/mkdocs.yml +++ b/{{cookiecutter.project_slug}}/mkdocs.yml @@ -6,6 +6,11 @@ repo_url: "https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.pr repo_name: "{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}" edit_uri: edit/main/docs/ +validation: + omitted_files: warn + absolute_links: warn + unrecognized_links: warn + theme: name: "material" palette: From 0de39ae5630f66eb605679d4c83f2e14cb702a6c Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Thu, 21 Mar 2024 08:39:16 +0000 Subject: [PATCH 08/24] Add GitHub social link --- {{cookiecutter.project_slug}}/mkdocs.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/{{cookiecutter.project_slug}}/mkdocs.yml b/{{cookiecutter.project_slug}}/mkdocs.yml index bf555372..b4f0ca97 100644 --- a/{{cookiecutter.project_slug}}/mkdocs.yml +++ b/{{cookiecutter.project_slug}}/mkdocs.yml @@ -45,3 +45,8 @@ plugins: import: - "https://docs.python.org/3/objects.inv" paths: [src] + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/{{cookiecutter.github_username}} From 81fa6252f580302cc3b9aed46523218984bf7154 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Thu, 21 Mar 2024 08:40:15 +0000 Subject: [PATCH 09/24] Include README and license content in docs --- {{cookiecutter.project_slug}}/docs/index.md | 4 +--- {{cookiecutter.project_slug}}/docs/license.md | 1 + {{cookiecutter.project_slug}}/mkdocs.yml | 9 +++++++-- 3 files changed, 9 insertions(+), 5 deletions(-) create mode 100644 {{cookiecutter.project_slug}}/docs/license.md diff --git a/{{cookiecutter.project_slug}}/docs/index.md b/{{cookiecutter.project_slug}}/docs/index.md index 9a2264c7..612c7a5e 100644 --- a/{{cookiecutter.project_slug}}/docs/index.md +++ b/{{cookiecutter.project_slug}}/docs/index.md @@ -1,3 +1 @@ -# {{cookiecutter.project_name}} - -{{cookiecutter.project_short_description}} +--8<-- "README.md" diff --git a/{{cookiecutter.project_slug}}/docs/license.md b/{{cookiecutter.project_slug}}/docs/license.md new file mode 100644 index 00000000..af216c61 --- /dev/null +++ b/{{cookiecutter.project_slug}}/docs/license.md @@ -0,0 +1 @@ +--8<-- "LICENSE.md" diff --git a/{{cookiecutter.project_slug}}/mkdocs.yml b/{{cookiecutter.project_slug}}/mkdocs.yml index b4f0ca97..fb8bd1dc 100644 --- a/{{cookiecutter.project_slug}}/mkdocs.yml +++ b/{{cookiecutter.project_slug}}/mkdocs.yml @@ -32,8 +32,13 @@ theme: repo: fontawesome/brands/github nav: - - index.md - - api.md + - Overview: index.md + - API reference: api.md + - License: license.md + +markdown_extensions: + - pymdownx.tasklist + - pymdownx.snippets plugins: - search From 248f1f31f5f66f4843f7ab000165809c221f4666 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Thu, 21 Mar 2024 08:40:30 +0000 Subject: [PATCH 10/24] Tweak copyright line --- {{cookiecutter.project_slug}}/mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{cookiecutter.project_slug}}/mkdocs.yml b/{{cookiecutter.project_slug}}/mkdocs.yml index fb8bd1dc..e996465f 100644 --- a/{{cookiecutter.project_slug}}/mkdocs.yml +++ b/{{cookiecutter.project_slug}}/mkdocs.yml @@ -1,7 +1,7 @@ site_name: "{{cookiecutter.project_name}}" site_description: "Documentation website for {{cookiecutter.project_name}}" site_author: "{{cookiecutter.author_given_names}} {{cookiecutter.author_family_names}}" -copyright: "© {% now 'utc', '%Y' %}, {{cookiecutter.author_given_names}} {{cookiecutter.author_family_names}}" +copyright: "Copyright © {% now 'utc', '%Y' %} {{cookiecutter.author_given_names}} {{cookiecutter.author_family_names}}" repo_url: "https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/" repo_name: "{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}" edit_uri: edit/main/docs/ From 0648c3a9b3abcd70287126f6ebca47124cfef138 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Thu, 21 Mar 2024 08:45:52 +0000 Subject: [PATCH 11/24] Correct reference to docs dependencies --- {{cookiecutter.project_slug}}/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{cookiecutter.project_slug}}/README.md b/{{cookiecutter.project_slug}}/README.md index fedfa29b..214d1737 100644 --- a/{{cookiecutter.project_slug}}/README.md +++ b/{{cookiecutter.project_slug}}/README.md @@ -123,7 +123,7 @@ from the root of the repository. The built documentation will be written to `site`. Alternatively to build and preview the documentation locally, in a Python environment -with the development dependencies installed, run +with the optional `docs` dependencies installed, run ```sh mkdocs serve From 04884a513e25425bc2c6a3c83966d2e820a817d6 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Thu, 21 Mar 2024 09:13:28 +0000 Subject: [PATCH 12/24] Rename license file in docs to make relative link from README work --- {{cookiecutter.project_slug}}/docs/{license.md => LICENSE.md} | 0 {{cookiecutter.project_slug}}/mkdocs.yml | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename {{cookiecutter.project_slug}}/docs/{license.md => LICENSE.md} (100%) diff --git a/{{cookiecutter.project_slug}}/docs/license.md b/{{cookiecutter.project_slug}}/docs/LICENSE.md similarity index 100% rename from {{cookiecutter.project_slug}}/docs/license.md rename to {{cookiecutter.project_slug}}/docs/LICENSE.md diff --git a/{{cookiecutter.project_slug}}/mkdocs.yml b/{{cookiecutter.project_slug}}/mkdocs.yml index e996465f..dbdd5c2d 100644 --- a/{{cookiecutter.project_slug}}/mkdocs.yml +++ b/{{cookiecutter.project_slug}}/mkdocs.yml @@ -34,7 +34,7 @@ theme: nav: - Overview: index.md - API reference: api.md - - License: license.md + - License: LICENSE.md markdown_extensions: - pymdownx.tasklist From f16841b533830366c7bd8ad54d68daeccb3d0d22 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Thu, 21 Mar 2024 09:13:44 +0000 Subject: [PATCH 13/24] Add edit buttons to docs --- {{cookiecutter.project_slug}}/mkdocs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/{{cookiecutter.project_slug}}/mkdocs.yml b/{{cookiecutter.project_slug}}/mkdocs.yml index dbdd5c2d..9a355762 100644 --- a/{{cookiecutter.project_slug}}/mkdocs.yml +++ b/{{cookiecutter.project_slug}}/mkdocs.yml @@ -13,6 +13,8 @@ validation: theme: name: "material" + features: + - content.action.edit palette: - media: "(prefers-color-scheme)" toggle: From 442992ef04ce0988f5e6317c31f8200c38e7503c Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Fri, 22 Mar 2024 15:48:41 +0000 Subject: [PATCH 14/24] Apply suggestions from code review Co-authored-by: Patrick J. Roddy --- {{cookiecutter.project_slug}}/.github/workflows/docs.yml | 2 +- {{cookiecutter.project_slug}}/pyproject.toml | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml index e8160daf..d05f452d 100644 --- a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml +++ b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml @@ -7,7 +7,7 @@ on: pull_request: jobs: - build: + docs: runs-on: ubuntu-latest steps: - name: Checkout source diff --git a/{{cookiecutter.project_slug}}/pyproject.toml b/{{cookiecutter.project_slug}}/pyproject.toml index f86f11a7..748ce163 100644 --- a/{{cookiecutter.project_slug}}/pyproject.toml +++ b/{{cookiecutter.project_slug}}/pyproject.toml @@ -139,6 +139,7 @@ legacy_tox_ini = """ [testenv:docs] commands = - mkdocs build -s - extras = docs + mkdocs build --strict + extras = + docs """ From 2e6753370d3145da6798aa1d7ca3190a6f7cf8d4 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Fri, 22 Mar 2024 15:52:47 +0000 Subject: [PATCH 15/24] Reorder tox testenv sections Co-authored-by: Patrick J. Roddy --- {{cookiecutter.project_slug}}/pyproject.toml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/{{cookiecutter.project_slug}}/pyproject.toml b/{{cookiecutter.project_slug}}/pyproject.toml index 748ce163..3b312844 100644 --- a/{{cookiecutter.project_slug}}/pyproject.toml +++ b/{{cookiecutter.project_slug}}/pyproject.toml @@ -128,6 +128,12 @@ legacy_tox_ini = """ extras = test + [testenv:docs] + commands = + mkdocs build --strict + extras = + docs + [tox] env_list = {%- for python_version in range( @@ -136,10 +142,4 @@ legacy_tox_ini = """ ) %} py3{{python_version}} {%- endfor %} - - [testenv:docs] - commands = - mkdocs build --strict - extras = - docs """ From f48174e5b804bd9fca9c5b8ae9d03691b80a3e5a Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Fri, 22 Mar 2024 15:53:03 +0000 Subject: [PATCH 16/24] Add quotation marks around URL for consistency --- {{cookiecutter.project_slug}}/mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{cookiecutter.project_slug}}/mkdocs.yml b/{{cookiecutter.project_slug}}/mkdocs.yml index 9a355762..14888c56 100644 --- a/{{cookiecutter.project_slug}}/mkdocs.yml +++ b/{{cookiecutter.project_slug}}/mkdocs.yml @@ -56,4 +56,4 @@ plugins: extra: social: - icon: fontawesome/brands/github - link: https://github.com/{{cookiecutter.github_username}} + link: "https://github.com/{{cookiecutter.github_username}}" From 483a19e10ae863c0b288765d207120e250eb4377 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Fri, 22 Mar 2024 16:01:23 +0000 Subject: [PATCH 17/24] Add vertical spacing between docs workflow job steps for consistency Co-authored-by: Patrick J. Roddy --- {{cookiecutter.project_slug}}/.github/workflows/docs.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml index d05f452d..c4da5bf3 100644 --- a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml +++ b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml @@ -12,21 +12,25 @@ jobs: 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), From 2f6bace5b41954f5295c9e066df669726281de67 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Fri, 22 Mar 2024 16:09:22 +0000 Subject: [PATCH 18/24] Adjust commented section indentation --- .../.github/workflows/docs.yml | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml index c4da5bf3..b4da760a 100644 --- a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml +++ b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml @@ -30,17 +30,17 @@ jobs: 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: site - # publish_branch: gh-pages - # user_name: "github-actions[bot]" - # user_email: "github-actions[bot]@users.noreply.github.com" + + # 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: site + # publish_branch: gh-pages + # user_name: "github-actions[bot]" + # user_email: "github-actions[bot]@users.noreply.github.com" From c36eb4f23c2685dbd91d3aded68c4e2d08897767 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Fri, 22 Mar 2024 16:12:46 +0000 Subject: [PATCH 19/24] Remove spaces on empty lines --- {{cookiecutter.project_slug}}/.github/workflows/docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml index b4da760a..5a9ffe06 100644 --- a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml +++ b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml @@ -25,12 +25,12 @@ jobs: 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), From dfa918ade36dbb78cf60b8c460a05e89080aa76d Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Fri, 22 Mar 2024 16:34:37 +0000 Subject: [PATCH 20/24] Add option to enable automatically docs to GitHub Pages to cookiecutter --- cookiecutter.json | 6 +++- .../.github/workflows/docs.yml | 29 ++++++++++--------- 2 files changed, 20 insertions(+), 15 deletions(-) diff --git a/cookiecutter.json b/cookiecutter.json index 3fdda2c9..26a671c4 100644 --- a/cookiecutter.json +++ b/cookiecutter.json @@ -7,9 +7,13 @@ "package_name": "{{cookiecutter.project_slug.replace('-', '_')}}", "project_short_description": "A cookiecutter template with ARC recommendations.", "initialise_git_repository": true, + "deploy_docs_to_github_pages": false, "github_username": "{{cookiecutter.author_given_names.lower().replace(' ', '-')}}-{{cookiecutter.author_family_names.lower().replace(' ', '-')}}", "min_python_version": ["3.9", "3.10", "3.11", "3.12"], "max_python_version": ["3.12", "3.11", "3.10", "3.9"], "license": ["MIT", "BSD-3", "GPL-3.0"], - "funder": "JBFC: The Joe Bloggs Funding Council" + "funder": "JBFC: The Joe Bloggs Funding Council", + "__prompts__": { + "deploy_docs_to_github_pages": "Enable automatically deploying HTML documentation to GitHub Pages website on pushes to main" + } } diff --git a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml index 5a9ffe06..fd46fa08 100644 --- a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml +++ b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml @@ -30,17 +30,18 @@ jobs: 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: site - # publish_branch: gh-pages - # user_name: "github-actions[bot]" - # user_email: "github-actions[bot]@users.noreply.github.com" +{% if cookiecutter.deploy_docs_to_github_pages %} + # Automatically deploy documentation to a GitHub Pages website on pushing to main. + # Requires configuring the repository to deploy GitHub pages 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: site + publish_branch: gh-pages + user_name: "github-actions[bot]" + user_email: "github-actions[bot]@users.noreply.github.com" +{%- endif %} From 5c874cf93d0f89da5ec4845c5496f3b7c468019c Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Fri, 22 Mar 2024 16:54:02 +0000 Subject: [PATCH 21/24] Adjust newlines and whitespace control in template to satisfy prettier --- {{cookiecutter.project_slug}}/.github/workflows/docs.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml index fd46fa08..12235db0 100644 --- a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml +++ b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml @@ -30,7 +30,8 @@ jobs: run: python -m pip install tox - name: Build HTML documentation with tox run: tox -e docs -{% if cookiecutter.deploy_docs_to_github_pages %} +{%- if cookiecutter.deploy_docs_to_github_pages %} + # Automatically deploy documentation to a GitHub Pages website on pushing to main. # Requires configuring the repository to deploy GitHub pages from a branch # gh-pages (https://tinyurl.com/gh-pages-from-branch), which will be created the From c23d7e6626b52011f221d0ca5ffe0aa94b3592ae Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Fri, 22 Mar 2024 17:12:39 +0000 Subject: [PATCH 22/24] Switch from pymdownx.snippets extension to mkdocs-include-markdown-plugin --- {{cookiecutter.project_slug}}/docs/LICENSE.md | 4 +++- {{cookiecutter.project_slug}}/docs/index.md | 5 ++++- {{cookiecutter.project_slug}}/mkdocs.yml | 4 +++- {{cookiecutter.project_slug}}/pyproject.toml | 1 + 4 files changed, 11 insertions(+), 3 deletions(-) diff --git a/{{cookiecutter.project_slug}}/docs/LICENSE.md b/{{cookiecutter.project_slug}}/docs/LICENSE.md index af216c61..5fc755ad 100644 --- a/{{cookiecutter.project_slug}}/docs/LICENSE.md +++ b/{{cookiecutter.project_slug}}/docs/LICENSE.md @@ -1 +1,3 @@ ---8<-- "LICENSE.md" +{! + include-markdown "../LICENSE.md" +!} diff --git a/{{cookiecutter.project_slug}}/docs/index.md b/{{cookiecutter.project_slug}}/docs/index.md index 612c7a5e..8ab94821 100644 --- a/{{cookiecutter.project_slug}}/docs/index.md +++ b/{{cookiecutter.project_slug}}/docs/index.md @@ -1 +1,4 @@ ---8<-- "README.md" +{! + include-markdown "../README.md" + rewrite-relative-urls=false +!} diff --git a/{{cookiecutter.project_slug}}/mkdocs.yml b/{{cookiecutter.project_slug}}/mkdocs.yml index 14888c56..36b2bb3f 100644 --- a/{{cookiecutter.project_slug}}/mkdocs.yml +++ b/{{cookiecutter.project_slug}}/mkdocs.yml @@ -40,7 +40,6 @@ nav: markdown_extensions: - pymdownx.tasklist - - pymdownx.snippets plugins: - search @@ -52,6 +51,9 @@ plugins: import: - "https://docs.python.org/3/objects.inv" paths: [src] + - include-markdown: + opening_tag: "{!" + closing_tag: "!}" extra: social: diff --git a/{{cookiecutter.project_slug}}/pyproject.toml b/{{cookiecutter.project_slug}}/pyproject.toml index 3b312844..8f3f2d10 100644 --- a/{{cookiecutter.project_slug}}/pyproject.toml +++ b/{{cookiecutter.project_slug}}/pyproject.toml @@ -39,6 +39,7 @@ optional-dependencies = {dev = [ "twine", ], docs = [ "mkdocs", + "mkdocs-include-markdown-plugin", "mkdocs-material", "mkdocstrings", "mkdocstrings-python", From 832b2624cddb5961a0fcf9793cd30157bd8185dc Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Fri, 22 Mar 2024 17:18:24 +0000 Subject: [PATCH 23/24] Remove indentation in include-markdown directive to satisfy prettier --- {{cookiecutter.project_slug}}/docs/LICENSE.md | 2 +- {{cookiecutter.project_slug}}/docs/index.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/{{cookiecutter.project_slug}}/docs/LICENSE.md b/{{cookiecutter.project_slug}}/docs/LICENSE.md index 5fc755ad..606f09a3 100644 --- a/{{cookiecutter.project_slug}}/docs/LICENSE.md +++ b/{{cookiecutter.project_slug}}/docs/LICENSE.md @@ -1,3 +1,3 @@ {! - include-markdown "../LICENSE.md" +include-markdown "../LICENSE.md" !} diff --git a/{{cookiecutter.project_slug}}/docs/index.md b/{{cookiecutter.project_slug}}/docs/index.md index 8ab94821..61196b9f 100644 --- a/{{cookiecutter.project_slug}}/docs/index.md +++ b/{{cookiecutter.project_slug}}/docs/index.md @@ -1,4 +1,4 @@ {! - include-markdown "../README.md" - rewrite-relative-urls=false +include-markdown "../README.md" +rewrite-relative-urls=false !} From fbb1d626c5601e7edcc2a5f153585ebd0905fd59 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Mon, 25 Mar 2024 09:18:58 +0000 Subject: [PATCH 24/24] Update {{cookiecutter.project_slug}}/README.md Co-authored-by: Sam Cunliffe --- {{cookiecutter.project_slug}}/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{cookiecutter.project_slug}}/README.md b/{{cookiecutter.project_slug}}/README.md index 214d1737..12262a0f 100644 --- a/{{cookiecutter.project_slug}}/README.md +++ b/{{cookiecutter.project_slug}}/README.md @@ -3,7 +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] +[![Documentation status][documentation-badge]][documentation-link] [![License][license-badge]](./LICENSE.md)