Skip to content

Commit 8602c68

Browse files
mbercxmbercx
committed
📚 Template: update developer instructions
Now that we offer more options with regard to devops tools, we document the various approaches in separate tabs. To support tabs, we add the `pymdownx.superfences` and `pymdownx.tabbed` extensions to the MkDocs config. Although `pymdownx.blocks.tab` is newer, it seems to be not fully supported yet, at least in Material for MkDocs. Because the MyST tab syntax does not allow indentation, and the MkDocs one with `pymdownx.tabbed` requires it, there is quite a bit of duplication in the Jinja template for the developer docs. We should look into approaches to avoid duplication in the future.
1 parent d60d634 commit 8602c68

File tree

2 files changed

+321
-21
lines changed

2 files changed

+321
-21
lines changed

‎template/docs/developer.md.jinja‎

Lines changed: 318 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,344 @@
11
# Developer Guide
22

3-
## Hatch
3+
## Quick start
44

5-
We use [Hatch](https://hatch.pypa.io/latest) to set up environments and scripts for most developer tasks.
5+
Thanks for contributing! 🙏
6+
Below you can find an overview of the commands to get you up and running quickly.
7+
8+
First clone the repository from GitHub
9+
10+
git clone <GITHUB-REPO>
11+
12+
and install the package locally in **editable** mode (`-e`):
13+
14+
cd {{ package_name }}
15+
pip install -e .
16+
17+
{% if docs == 'myst'-%}
18+
:::{note}
19+
We support various tools for developers.
20+
Select your preferred one from the tabs below.
21+
If you don't know `uv` or Hatch, stick with the default for now.
22+
:::
23+
24+
::::{tab-set}
25+
:::{tab-item} Default
26+
27+
The "default" approach to developing is to install the development extras in your current environment:
28+
29+
pip install -e .[pre-commit,tests,docs]
30+
31+
🔧 **Pre-commit**
32+
33+
To make sure your changes adhere to our formatting/linting preferences, install the pre-commit hooks:
34+
35+
pre-commit install
36+
37+
They will then run on every `git commit`.
38+
You can also run them on e.g. all files using:
39+
40+
pre-commit run -a
41+
42+
Drop the `-a` option in case you only want to run on staged files.
43+
44+
🧪 **Tests**
45+
46+
You can run all tests in the `tests` directory with `pytest`:
47+
48+
pytest
49+
50+
Or select the test module:
51+
52+
pytest tests/parsers/test_pw.py
53+
54+
See the [`pytest` documentation](https://docs.pytest.org/en/stable/how-to/usage.html#specifying-which-tests-to-run) for more information.
55+
56+
📚 **Documentation**
57+
58+
We use [MyST](https://mystmd.org/) as our documentation framework.
59+
Go into the `docs` directory and start the documentation server with:
60+
61+
myst start
62+
63+
and open the documentation in your browser via the link shown.
64+
Every time you save a file, the corresponding documentation page is updated automatically!
65+
{%- if doc_deploy == 'github' %}
66+
67+
A GitHub action is set up to automatically deploy the documentation to GitHub Pages.
68+
See [the corresponding GitHub Pages documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch) for the steps required.
69+
{%- endif %}
70+
71+
:::
72+
:::{tab-item} uv
73+
74+
`uv` is a Python package and project manager.
75+
See [the documentation](https://docs.astral.sh/uv/getting-started/installation/) on how to install `uv`.
76+
77+
🔧 **Pre-commit**
78+
79+
To make sure your changes adhere to our formatting/linting preferences, install the pre-commit hooks:
80+
81+
uvx pre-commit install
82+
83+
They will then run on every `git commit`.
84+
You can also run them on e.g. all files using:
85+
86+
uvx pre-commit run -a
87+
88+
Drop the `-a` option in case you only want to run on staged files.
89+
90+
```{note}
91+
Here we use the [`uvx` command](https://docs.astral.sh/uv/guides/tools/#running-tools) to run the `pre-commit` tool without installing it.
92+
Alternatively you can also install [`pre-commit` as a tool](https://docs.astral.sh/uv/guides/tools/#installing-tools) and omit `uvx`.
93+
```
94+
95+
🧪 **Tests**
96+
97+
You can run all tests in the `tests` directory with `pytest`:
98+
99+
uv run pytest
100+
101+
Or select the test module:
102+
103+
uv run pytest tests/parsers/test_pw.py
104+
105+
See the [`pytest` documentation](https://docs.pytest.org/en/stable/how-to/usage.html#specifying-which-tests-to-run) for more information.
106+
107+
📚 **Documentation**
108+
109+
We use [MyST](https://mystmd.org/) as our documentation framework.
110+
Go into the `docs` directory and start the documentation server with:
111+
112+
myst start
113+
114+
and open the documentation in your browser via the link shown.
115+
Every time you save a file, the corresponding documentation page is updated automatically!
116+
{%- if doc_deploy == 'github' %}
117+
118+
A GitHub action is set up to automatically deploy the documentation to GitHub Pages.
119+
See [the corresponding GitHub Pages documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch) for the steps required.
120+
{%- endif %}
121+
122+
:::
123+
:::{tab-item} Hatch
124+
125+
You can use [Hatch](https://hatch.pypa.io/1.9/install/) to run development tools in isolated environments.
6126
To see a table of the available environments and their scripts, run:
7127

8128
hatch env show
9129

10-
### Documentation
130+
🔧 **Pre-commit**
11131

12-
The easiest way to work on the documentation is to start the server locally via:
132+
To make sure your changes adhere to our formatting/linting preferences, install the pre-commit hooks:
13133

14-
hatch run docs:serve
134+
hatch run pre-commit:install
135+
136+
They will then run on every `git commit`.
137+
You can also run them on e.g. all files using:
138+
139+
hatch run pre-commit:run -a
140+
141+
Drop the `-a` option in case you only want to run on staged files.
142+
143+
🧪 **Tests**
144+
145+
You can run all tests in the `tests` directory using:
146+
147+
hatch test
148+
149+
Or select the test module:
150+
151+
hatch test tests/parsers/test_pw.py
152+
153+
You can also run the tests for a specific Python version with the `-py` option:
154+
155+
hatch test -py 3.11
156+
157+
Or all supported Python `versions` with `--all`:
158+
159+
hatch test --all
160+
161+
See the [Hatch documentation](https://hatch.pypa.io/1.12/tutorials/testing/overview/) for more information.
15162

16-
And go to the provided URL.
17-
If you only want to build the documentation locally, there is also a script for that:
163+
📚 **Documentation**
18164

19-
hatch run docs:build
165+
We use [MyST](https://mystmd.org/) as our documentation framework.
166+
Start the documentation server with:
20167

168+
hatch run docs:serve
169+
170+
and open the documentation in your browser via the link shown.
171+
Every time you save a file, the corresponding documentation page is updated automatically!
21172
{%- if doc_deploy == 'github' %}
22173

23174
A GitHub action is set up to automatically deploy the documentation to GitHub Pages.
24175
See [the corresponding GitHub Pages documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch) for the steps required.
25176
{%- endif %}
26177

27-
### Pre-commit
178+
:::
179+
::::
180+
{%- endif %}
181+
{%- if docs == 'mkdocs' -%}
182+
!!! note
183+
We support various tools for developers.
184+
Select your preferred one from the tabs below.
185+
If you don't know `uv` or Hatch, stick with the default for now.
186+
187+
=== "Default"
188+
189+
The "default" approach to developing is to install the development extras in your current environment:
190+
191+
pip install -e .[pre-commit,tests,docs]
192+
193+
🔧 **Pre-commit**
194+
195+
To make sure your changes adhere to our formatting/linting preferences, install the pre-commit hooks:
196+
197+
pre-commit install
198+
199+
They will then run on every `git commit`.
200+
You can also run them on e.g. all files using:
201+
202+
pre-commit run -a
203+
204+
Drop the `-a` option in case you only want to run on staged files.
205+
206+
🧪 **Tests**
207+
208+
You can run all tests in the `tests` directory with `pytest`:
209+
210+
pytest
211+
212+
Or select the test module:
213+
214+
pytest tests/parsers/test_pw.py
215+
216+
See the [`pytest` documentation](https://docs.pytest.org/en/stable/how-to/usage.html#specifying-which-tests-to-run) for more information.
217+
218+
📚 **Documentation**
219+
220+
We use [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) as our documentation framework.
221+
Start the documentation server with:
222+
223+
mkdocs serve
224+
225+
and open the documentation in your browser via the link shown.
226+
Every time you save a file, the corresponding documentation page is updated automatically!
227+
{%- if doc_deploy == 'github' %}
228+
229+
A GitHub action is set up to automatically deploy the documentation to GitHub Pages.
230+
See [the corresponding GitHub Pages documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch) for the steps required.
231+
{%- endif %}
232+
233+
=== "uv"
234+
235+
`uv` is a Python package and project manager.
236+
See [the documentation](https://docs.astral.sh/uv/getting-started/installation/) on how to install `uv`.
237+
238+
🔧 **Pre-commit**
239+
240+
To make sure your changes adhere to our formatting/linting preferences, install the pre-commit hooks:
241+
242+
uvx pre-commit install
243+
244+
They will then run on every `git commit`.
245+
You can also run them on e.g. all files using:
246+
247+
uvx pre-commit run -a
248+
249+
Drop the `-a` option in case you only want to run on staged files.
250+
251+
!!! note
252+
Here we use the [`uvx` command](https://docs.astral.sh/uv/guides/tools/#running-tools) to run the `pre-commit` tool without installing it.
253+
Alternatively you can also install [`pre-commit` as a tool](https://docs.astral.sh/uv/guides/tools/#installing-tools) and omit `uvx`.
254+
255+
🧪 **Tests**
256+
257+
You can run all tests in the `tests` directory with `pytest`:
258+
259+
uv run pytest
28260

29-
You can install the [pre-commit](https://pre-commit.com/) hooks with:
261+
Or select the test module:
30262

31-
hatch run precommit:install
263+
uv run pytest tests/parsers/test_pw.py
32264

33-
Or run them via:
265+
See the [`pytest` documentation](https://docs.pytest.org/en/stable/how-to/usage.html#specifying-which-tests-to-run) for more information.
34266

35-
hatch run precommit:run
267+
📚 **Documentation**
36268

37-
From the extensive [Ruff ruleset](https://docs.astral.sh/ruff/rules/) that Hatch uses, we ignore the following globally:
269+
We use [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) as our documentation framework.
270+
Start the documentation server with:
271+
272+
mkdocs serve
273+
274+
and open the documentation in your browser via the link shown.
275+
Every time you save a file, the corresponding documentation page is updated automatically!
276+
{%- if doc_deploy == 'github' %}
277+
278+
A GitHub action is set up to automatically deploy the documentation to GitHub Pages.
279+
See [the corresponding GitHub Pages documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch) for the steps required.
280+
{%- endif %}
281+
282+
=== "Hatch"
283+
284+
You can use [Hatch](https://hatch.pypa.io/1.9/install/) to run development tools in isolated environments.
285+
To see a table of the available environments and their scripts, run:
286+
287+
hatch env show
288+
289+
🔧 **Pre-commit**
290+
291+
To make sure your changes adhere to our formatting/linting preferences, install the pre-commit hooks:
292+
293+
hatch run pre-commit:install
294+
295+
They will then run on every `git commit`.
296+
You can also run them on e.g. all files using:
297+
298+
hatch run pre-commit:run -a
299+
300+
Drop the `-a` option in case you only want to run on staged files.
301+
302+
🧪 **Tests**
303+
304+
You can run all tests in the `tests` directory using:
305+
306+
hatch test
307+
308+
Or select the test module:
309+
310+
hatch test tests/parsers/test_pw.py
311+
312+
You can also run the tests for a specific Python version with the `-py` option:
313+
314+
hatch test -py 3.11
315+
316+
Or all supported Python `versions` with `--all`:
317+
318+
hatch test --all
319+
320+
See the [Hatch documentation](https://hatch.pypa.io/1.12/tutorials/testing/overview/) for more information.
321+
322+
📚 **Documentation**
323+
324+
We use [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) as our documentation framework.
325+
Start the documentation server with:
326+
327+
hatch run docs:serve
328+
329+
and open the documentation in your browser via the link shown.
330+
Every time you save a file, the corresponding documentation page is updated automatically!
331+
{%- if doc_deploy == 'github' %}
332+
333+
A GitHub action is set up to automatically deploy the documentation to GitHub Pages.
334+
See [the corresponding GitHub Pages documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch) for the steps required.
335+
{%- endif %}
336+
{%- endif %}
337+
338+
339+
## Pre-commit rules
340+
341+
From the extensive [Ruff ruleset](https://docs.astral.sh/ruff/rules/), we ignore the following globally:
38342

39343
| Code | Rule | Rationale / Note |
40344
| --------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
@@ -51,10 +355,3 @@ And the following rules for the files in the `tests` directory:
51355
| --------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
52356
| `INP001` | [implicit-namespace-package](https://docs.astral.sh/ruff/rules/implicit-namespace-package/) | When tests are not part of the package, there is no need for `__init__.py` files. |
53357
| `S101` | [assert](https://docs.astral.sh/ruff/rules/assert/) | Asserts should not be used in production environments, but are fine for tests. |
54-
55-
### Tests
56-
57-
Tests are written using the [`pytest` package](https://docs.pytest.org/en/stable/index.html).
58-
They can be run using:
59-
60-
hatch run tests:run

‎template/{% if docs == 'mkdocs' %}mkdocs.yml{% endif %}.jinja‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,6 @@ theme:
55

66
markdown_extensions:
77
- admonition
8+
- pymdownx.superfences
9+
- pymdownx.tabbed:
10+
alternate_style: true

0 commit comments

Comments
 (0)