Skip to content

Commit 773e4dc

Browse files
samcunliffesamcunliffe
authored
Merge branch 'main' into sc/103-best-practices
2 parents ea9a9a8 + 925fce9 commit 773e4dc

File tree

12 files changed

+188
-12
lines changed

12 files changed

+188
-12
lines changed

‎cookiecutter.json

+5-1
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,13 @@
77
"package_name": "{{cookiecutter.project_slug.replace('-', '_')}}",
88
"project_short_description": "A cookiecutter template with ARC recommendations.",
99
"initialise_git_repository": true,
10+
"deploy_docs_to_github_pages": false,
1011
"github_username": "{{cookiecutter.author_given_names.lower().replace(' ', '-')}}-{{cookiecutter.author_family_names.lower().replace(' ', '-')}}",
1112
"min_python_version": ["3.9", "3.10", "3.11", "3.12"],
1213
"max_python_version": ["3.12", "3.11", "3.10", "3.9"],
1314
"license": ["MIT", "BSD-3", "GPL-3.0"],
14-
"funder": "JBFC: The Joe Bloggs Funding Council"
15+
"funder": "JBFC: The Joe Bloggs Funding Council",
16+
"__prompts__": {
17+
"deploy_docs_to_github_pages": "Enable automatically deploying HTML documentation to GitHub Pages website on pushes to main"
18+
}
1519
}

‎docs/pages/ci.md

+7-6
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,13 @@ layout: default
55

66
# Continuous integration
77

8-
| Name | Short description | 🚦 |
9-
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | :-: |
10-
| [GitHub Actions](https://docs.github.com/en/actions) | Continuous integration and continuous delivery platform (integrated with GitHub). | 🟢 |
11-
| [AppVeyor](https://www.appveyor.com/docs/) | Continuous integration and continuous delivery platform. | 🟠 |
12-
| [Bamboo](https://confluence.atlassian.com/bamboo/bamboo-documentation-289276551.html) | Atlassian continuous integration and continuous delivery platform. | 🟠 |
13-
| [Travis CI](https://docs.travis-ci.com/) | Continuous integration and continuous delivery platform. | 🟠 |
8+
| Name | Short description | 🚦 |
9+
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
10+
| [GitHub Actions](https://docs.github.com/en/actions) | Continuous integration and continuous delivery platform (integrated with GitHub). | 🟢 |
11+
| [AppVeyor](https://www.appveyor.com/docs/) | Continuous integration and continuous delivery platform. | 🟠 |
12+
| [Bamboo](https://confluence.atlassian.com/bamboo/bamboo-documentation-289276551.html) | Atlassian continuous integration and continuous delivery platform. | 🟠 |
13+
| [Travis CI](https://docs.travis-ci.com/) | Continuous integration and continuous delivery platform. | 🟠 |
14+
| [pre-commmit.ci](https://pre-commit.ci/) | A bot that adds a pre-commit job to your GitHub Actions CI, and can automatically fix most trivial linting failures. Free for open-source projects. | 🟢 |
1415

1516
<details>
1617
<summary> 🟢 explanation</summary>

‎docs/pages/docs.md

+1
Original file line numberDiff line numberDiff line change
@@ -24,3 +24,4 @@ Sphinx is the de-facto standard that is widely used. It is well tested, reliable
2424
| Name | Short description | 🚦 |
2525
| -------------------------------------------------------------------- | --------------------------------------------------------------- | :-: |
2626
| [sphinx-gallery](https://sphinx-gallery.github.io/stable/index.html) | Builds an HTML gallery of examples from a set of Python scripts | 🟢 |
27+
| [sphinx-autoapi](https://sphinx-autoapi.readthedocs.io/en/stable/) | Automatically generates API reference pages. | 🟢 |

‎tests/test_package_gen.py

+3
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,9 @@ def test_package_generation(
5656
"tests",
5757
pathlib.Path(".github"),
5858
pathlib.Path(".github") / "workflows",
59+
"mkdocs.yml",
60+
pathlib.Path("docs") / "index.md",
61+
pathlib.Path("docs") / "api.md",
5962
]
6063
for f in expected_files:
6164
full_path = test_project_dir / f

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

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
9+
jobs:
10+
docs:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: Checkout source
14+
uses: actions/checkout@v4
15+
16+
- name: Cache tox
17+
uses: actions/cache@v4
18+
with:
19+
path: .tox
20+
key: tox-${{ '{{' }} hashFiles('pyproject.toml') {{ '}}' }}
21+
22+
- name: Set up Python
23+
uses: actions/setup-python@v4
24+
with:
25+
python-version: "3.x"
26+
cache: "pip"
27+
cache-dependency-path: "pyproject.toml"
28+
29+
- name: Install tox
30+
run: python -m pip install tox
31+
- name: Build HTML documentation with tox
32+
run: tox -e docs
33+
{%- if cookiecutter.deploy_docs_to_github_pages %}
34+
35+
# Automatically deploy documentation to a GitHub Pages website on pushing to main.
36+
# Requires configuring the repository to deploy GitHub pages from a branch
37+
# gh-pages (https://tinyurl.com/gh-pages-from-branch), which will be created the
38+
# first time this workflow step is run.
39+
- name: Publish documentation on GitHub pages
40+
if: success() && github.event_name != 'pull_request'
41+
uses: peaceiris/actions-gh-pages@v3
42+
with:
43+
github_token: ${{ '{{' }} secrets.GITHUB_TOKEN {{ '}}' }}
44+
publish_dir: site
45+
publish_branch: gh-pages
46+
user_name: "github-actions[bot]"
47+
user_email: "github-actions[bot]@users.noreply.github.com"
48+
{%- endif %}

‎{{cookiecutter.project_slug}}/README.md

+24-3
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
44
[![Tests status][tests-badge]][tests-link]
55
[![Linting status][linting-badge]][linting-link]
6+
[![Documentation status][documentation-badge]][documentation-link]
67
[![License][license-badge]](./LICENSE.md)
78

89
<!--
@@ -16,6 +17,8 @@
1617
[tests-link]: https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/tests.yml
1718
[linting-badge]: https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/linting.yml/badge.svg
1819
[linting-link]: https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/linting.yml
20+
[documentation-badge]: https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/docs.yml/badge.svg
21+
[documentation-link]: https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/docs.yml
1922
[conda-badge]: https://img.shields.io/conda/vn/conda-forge/{{cookiecutter.project_slug}}
2023
[conda-link]: https://github.com/conda-forge/{{cookiecutter.project_slug}}-feedstock
2124
[pypi-link]: https://pypi.org/project/{{cookiecutter.project_slug}}/
@@ -51,9 +54,9 @@ Centre for Advanced Research Computing, University College London
5154

5255
<!-- TODO: can cookiecutter make a list of frameworks? -->
5356

54-
[Framework 1](https://something.com)
55-
[Framework 2](https://something.com)
56-
[Framework 3](https://something.com)
57+
- [Framework 1](https://something.com)
58+
- [Framework 2](https://something.com)
59+
- [Framework 3](https://something.com)
5760

5861
## Getting Started
5962

@@ -108,6 +111,24 @@ pytest tests
108111

109112
again from the root of the repository.
110113

114+
### Building Documentation
115+
116+
The MkDocs HTML documentation can be built locally by running
117+
118+
```sh
119+
tox -e docs
120+
```
121+
122+
from the root of the repository.
123+
The built documentation will be written to `site`.
124+
125+
Alternatively to build and preview the documentation locally, in a Python environment
126+
with the optional `docs` dependencies installed, run
127+
128+
```sh
129+
mkdocs serve
130+
```
131+
111132
## Roadmap
112133

113134
- [x] Initial Research

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

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{!
2+
include-markdown "../LICENSE.md"
3+
!}

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

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# API reference
2+
3+
::: {{cookiecutter.package_name}}

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

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{!
2+
include-markdown "../README.md"
3+
rewrite-relative-urls=false
4+
!}

‎{{cookiecutter.project_slug}}/mkdocs.yml

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
site_name: "{{cookiecutter.project_name}}"
2+
site_description: "Documentation website for {{cookiecutter.project_name}}"
3+
site_author: "{{cookiecutter.author_given_names}} {{cookiecutter.author_family_names}}"
4+
copyright: "Copyright © {% now 'utc', '%Y' %} {{cookiecutter.author_given_names}} {{cookiecutter.author_family_names}}"
5+
repo_url: "https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/"
6+
repo_name: "{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}"
7+
edit_uri: edit/main/docs/
8+
9+
validation:
10+
omitted_files: warn
11+
absolute_links: warn
12+
unrecognized_links: warn
13+
14+
theme:
15+
name: "material"
16+
features:
17+
- content.action.edit
18+
palette:
19+
- media: "(prefers-color-scheme)"
20+
toggle:
21+
icon: material/brightness-auto
22+
name: Switch to light mode
23+
- media: "(prefers-color-scheme: light)"
24+
scheme: default
25+
toggle:
26+
icon: material/brightness-7
27+
name: Switch to dark mode
28+
- media: "(prefers-color-scheme: dark)"
29+
scheme: slate
30+
toggle:
31+
icon: material/brightness-4
32+
name: Switch to system preference
33+
icon:
34+
repo: fontawesome/brands/github
35+
36+
nav:
37+
- Overview: index.md
38+
- API reference: api.md
39+
- License: LICENSE.md
40+
41+
markdown_extensions:
42+
- pymdownx.tasklist
43+
44+
plugins:
45+
- search
46+
- mkdocstrings:
47+
default_handler: python
48+
handlers:
49+
python:
50+
docstring_style: google
51+
import:
52+
- "https://docs.python.org/3/objects.inv"
53+
paths: [src]
54+
- include-markdown:
55+
opening_tag: "{!"
56+
closing_tag: "!}"
57+
58+
extra:
59+
social:
60+
- icon: fontawesome/brands/github
61+
link: "https://github.com/{{cookiecutter.github_username}}"

‎{{cookiecutter.project_slug}}/pyproject.toml

+14-2
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,12 @@ optional-dependencies = {dev = [
3737
"ruff",
3838
"tox",
3939
"twine",
40+
], docs = [
41+
"mkdocs",
42+
"mkdocs-include-markdown-plugin",
43+
"mkdocs-material",
44+
"mkdocstrings",
45+
"mkdocstrings-python",
4046
], test = [
4147
"pytest",
4248
"pytest-cov",
@@ -49,7 +55,7 @@ urls.homepage = "https://github.com/{{cookiecutter.github_username}}/{{cookiecut
4955
[tool.coverage]
5056
report = {sort = "cover"}
5157
run = {branch = true, parallel = true, source = [
52-
"{{cookiecutter.project_name}}",
58+
"{{cookiecutter.project_slug}}",
5359
]}
5460
paths.source = [
5561
"src",
@@ -88,7 +94,7 @@ lint.select = [
8894
"ALL",
8995
]
9096
lint.isort.known-first-party = [
91-
"{{cookiecutter.project_name}}",
97+
"{{cookiecutter.project_slug | replace('-', '_')}}",
9298
]
9399
lint.mccabe.max-complexity = 18
94100
lint.pep8-naming.classmethod-decorators = [
@@ -123,6 +129,12 @@ legacy_tox_ini = """
123129
extras =
124130
test
125131
132+
[testenv:docs]
133+
commands =
134+
mkdocs build --strict
135+
extras =
136+
docs
137+
126138
[tox]
127139
env_list =
128140
{%- for python_version in range(

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

+15
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,17 @@
11
"""{{cookiecutter.package_name}} package."""
22
from ._version import __version__ # noqa: F401
3+
4+
5+
def example_function(argument: str, keyword_argument: str = "default") -> str:
6+
"""
7+
Concatenate string arguments - an example function docstring.
8+
9+
Args:
10+
argument: An argument.
11+
keyword_argument: A keyword argument with a default value.
12+
13+
Returns:
14+
The concatenation of `argument` and `keyword_argument`.
15+
16+
"""
17+
return argument + keyword_argument

0 commit comments

Comments
 (0)