Adding MkDocs docs to template (#319)

Would resolve #16 as an alternative to #318

Adds MkDocs documentation to template, aiming for a comparable set of
features to what is implemented in #318 - automatically built API
documentation with Markdown syntax, support for references to external
documentation inventories, dark / light mode toggle, GitHub repository
link in docs, workflow for automatically testing building docs.

Example screenshot of rendered index page


![image](https://github.com/UCL-ARC/python-tooling/assets/6746980/e2578ed2-acd6-4322-8281-e21c1c4b9434)

and of API reference page


![image](https://github.com/UCL-ARC/python-tooling/assets/6746980/2d088c96-82ea-4a00-bff8-6e8e7d6e2aec)

---------

Co-authored-by: Patrick J. Roddy <patrickjamesroddy@gmail.com>
Co-authored-by: Sam Cunliffe <samcunliffe@users.noreply.github.com>

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"
+ }
 }

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

{{cookiecutter.project_slug}}/.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: Documentation
+
+on:
+ push:
+ branches:
+ - main
+ pull_request:
+
+jobs:
+ docs:
+ 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
+{%- 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 %}

{{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]][documentation-link]
 [![License][license-badge]](./LICENSE.md)
 
 <!--
@@ -16,6 +17,8 @@
 [tests-link]: https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/tests.yml
 [linting-badge]: https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/linting.yml/badge.svg
 [linting-link]: https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/linting.yml
+[documentation-badge]: https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/docs.yml/badge.svg
+[documentation-link]: https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/docs.yml
 [conda-badge]: https://img.shields.io/conda/vn/conda-forge/{{cookiecutter.project_slug}}
 [conda-link]: https://github.com/conda-forge/{{cookiecutter.project_slug}}-feedstock
 [pypi-link]: https://pypi.org/project/{{cookiecutter.project_slug}}/
@@ -51,9 +54,9 @@ Centre for Advanced Research Computing, University College London
 
 <!-- TODO: can cookiecutter make a list of frameworks? -->
 
-[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
 
@@ -108,6 +111,24 @@ pytest tests
 
 again from the root of the repository.
 
+### Building Documentation
+
+The MkDocs HTML documentation can be built locally by running
+
+```sh
+tox -e docs
+```
+
+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 optional `docs` dependencies installed, run
+
+```sh
+mkdocs serve
+```
+
 ## Roadmap
 
 - [x] Initial Research

{{cookiecutter.project_slug}}/docs/LICENSE.md

@@ -0,0 +1,3 @@
+{!
+include-markdown "../LICENSE.md"
+!}

{{cookiecutter.project_slug}}/docs/api.md

@@ -0,0 +1,3 @@
+# API reference
+
+::: {{cookiecutter.package_name}}

{{cookiecutter.project_slug}}/docs/index.md

@@ -0,0 +1,4 @@
+{!
+include-markdown "../README.md"
+rewrite-relative-urls=false
+!}

{{cookiecutter.project_slug}}/mkdocs.yml

@@ -0,0 +1,61 @@
+site_name: "{{cookiecutter.project_name}}"
+site_description: "Documentation website for {{cookiecutter.project_name}}"
+site_author: "{{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/
+
+validation:
+ omitted_files: warn
+ absolute_links: warn
+ unrecognized_links: warn
+
+theme:
+ name: "material"
+ features:
+ - content.action.edit
+ palette:
+ - media: "(prefers-color-scheme)"
+ toggle:
+ icon: material/brightness-auto
+ name: Switch to light mode
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
+ toggle:
+ icon: material/brightness-7
+ name: Switch to dark mode
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
+ toggle:
+ icon: material/brightness-4
+ name: Switch to system preference
+ icon:
+ repo: fontawesome/brands/github
+
+nav:
+ - Overview: index.md
+ - API reference: api.md
+ - License: LICENSE.md
+
+markdown_extensions:
+ - pymdownx.tasklist
+
+plugins:
+ - search
+ - mkdocstrings:
+ default_handler: python
+ handlers:
+ python:
+ docstring_style: google
+ import:
+ - "https://docs.python.org/3/objects.inv"
+ paths: [src]
+ - include-markdown:
+ opening_tag: "{!"
+ closing_tag: "!}"
+
+extra:
+ social:
+ - icon: fontawesome/brands/github
+ link: "https://github.com/{{cookiecutter.github_username}}"

{{cookiecutter.project_slug}}/pyproject.toml

@@ -37,6 +37,12 @@ optional-dependencies = {dev = [
  "ruff",
  "tox",
  "twine",
+], docs = [
+ "mkdocs",
+ "mkdocs-include-markdown-plugin",
+ "mkdocs-material",
+ "mkdocstrings",
+ "mkdocstrings-python",
 ], test = [
  "pytest",
  "pytest-cov",
@@ -123,6 +129,12 @@ legacy_tox_ini = """
  extras =
  test
 
+ [testenv:docs]
+ commands =
+ mkdocs build --strict
+ extras =
+ docs
+
  [tox]
  env_list =
  {%- for python_version in range(

{{cookiecutter.project_slug}}/src/{{cookiecutter.package_name}}/__init__.py

@@ -1,2 +1,17 @@
 """{{cookiecutter.package_name}} package."""
 from ._version import __version__ # noqa: F401
+
+
+def example_function(argument: str, keyword_argument: str = "default") -> str:
+ """
+ Concatenate string arguments - an example function docstring.
+
+ Args:
+ argument: An argument.
+ keyword_argument: A keyword argument with a default value.
+
+ Returns:
+ The concatenation of `argument` and `keyword_argument`.
+
+ """
+ return argument + keyword_argument