You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: {{cookiecutter.repository_name}}/CONTRIBUTING.md
+8-6
Original file line number
Diff line number
Diff line change
@@ -23,7 +23,7 @@ You can open an issue on GitHub to report bugs or request new {{ cookiecutter.re
23
23
Follow these links to submit your issue:
24
24
25
25
-[Report bugs or other problems while running {{ cookiecutter.repository_name }}](https://github.com/{{ cookiecutter.repository_owner }}/{{ cookiecutter.repository_name }}/issues/new?template=BUG-REPORT.yml).
26
-
If reporting an error, please include a full traceback in your issue.
26
+
If reporting an error, please include a full traceback in your issue.
27
27
28
28
-[Request features that {{ cookiecutter.repository_name }} does not already include](https://github.com/{{ cookiecutter.repository_owner }}/{{ cookiecutter.repository_name }}/issues/new?template=FEATURE-REQUEST.yml).
29
29
@@ -46,11 +46,11 @@ To contribute changes:
46
46
1. Commit your changes to the feature branch (you should have `pre-commit` installed to ensure your code is correctly formatted when you commit changes).
47
47
1. Push the branch to GitHub (`git push origin new-fix-or-feature`).
48
48
1. On GitHub, create a new [pull request](https://github.com/{{ cookiecutter.repository_owner }}/{{ cookiecutter.repository_name }}/pull/new/main) from the feature branch.
49
-
50
49
{%- if cookiecutter.create_author_file == "y" %}
51
-
When you contribute for the first time, ensure you add your name to the contributors list in `AUTHORS.md`!
52
50
51
+
When you contribute for the first time, ensure you add your name to the contributors list in `AUTHORS.md`!
53
52
{%- endif %}
53
+
54
54
### Pull requests
55
55
56
56
Before submitting a pull request, check whether you have:
@@ -65,10 +65,12 @@ When opening a pull request, please provide a clear summary of your changes!
65
65
66
66
Please try to write clear commit messages. One-line messages are fine for small changes, but bigger changes should look like this:
67
67
68
-
A brief summary of the commit (max 50 characters)
68
+
```text
69
+
A brief summary of the commit (max 50 characters)
69
70
70
-
A paragraph or bullet-point list describing what changed and its impact,
71
-
covering as many lines as needed.
71
+
A paragraph or bullet-point list describing what changed and its impact,
{% if cookiecutter.project_visibility == 'public' -%}
15
+
<!--- --8<-- [end:docs] -->
13
16
17
+
{% endif -%}
14
18
## Documentation
15
19
16
20
For more detailed instructions, see our [documentation](https://{{ cookiecutter.repository_owner }}.github.io/{{ cookiecutter.repository_name }}/latest).
@@ -25,10 +29,11 @@ To install {{ cookiecutter.module_name }}
25
29
Arup users on Windows can install `miniforge` from the Arup software shop by downloading "VS Code for Python" and then access `conda` from the VSCode integrated terminal.
For more detailed instructions, see our [documentation](https://{{ cookiecutter.repository_owner }}.github.io/{{ cookiecutter.repository_name }}/latest/installation/).
63
73
64
74
## Contributing
@@ -69,8 +79,8 @@ Before making contributions to the {{ cookiecutter.module_name }} source code, s
69
79
If you plan to make changes to the code then please make regular use of the following tools to verify the codebase while you work:
70
80
71
81
- `pre-commit`: run `pre-commit install`in your command line to load inbuilt checks that will run every time you commit your changes.
72
-
The checks are: 1. check no large files have been staged, 2. lint python files for major errors, 3. format python files to conform with the [pep8 standard](https://peps.python.org/pep-0008/).
73
-
You can also run these checks yourself at any time to ensure staged changes are clean by simple calling `pre-commit`.
82
+
The checks are: 1. check no large files have been staged, 2. lint python files for major errors, 3. format python files to conform with the [pep8 standard](https://peps.python.org/pep-0008/).
83
+
You can also run these checks yourself at any time to ensure staged changes are clean by simple calling `pre-commit`.
74
84
- `pytest` - run the unit test suite and check test coverage.
75
85
- `pytest -p memray -m "high_mem" --no-cov` (not available on Windows) - after installing memray (`conda install memray pytest-memray`), test that memory and time performance does not exceed benchmarks.
Copy file name to clipboardexpand all lines: {{cookiecutter.repository_name}}/docs/contributing.md
+15-12
Original file line number
Diff line number
Diff line change
@@ -31,7 +31,7 @@ To find beginner-friendly existing bugs and feature requests you may like to sta
31
31
To create a development environment for {{ cookiecutter.module_name }}, with all libraries required for development and quality assurance installed, it is easiest to install {{ cookiecutter.package_name }} using the [conda](https://docs.conda.io/en/latest/) package manager, as follows:
32
32
33
33
1. Install conda with the [miniforge](https://github.com/conda-forge/miniforge?tab=readme-ov-file#download) executable for your operating system.
34
-
Arup users on Windows can install `miniforge` from the Arup software shop by downloading "VS Code for Python".
34
+
Arup users on Windows can install `miniforge` from the Arup software shop by downloading "VS Code for Python".
35
35
1. Open the command line (or the VSCode "integrated terminal" in Windows).
1. Change into the `{{ cookiecutter.repository_name }}` directory: `cd {{ cookiecutter.repository_name }}`
@@ -52,11 +52,11 @@ Either way, you should add your environment as a jupyter kernel, so the example
52
52
If you plan to make changes to the code then please make regular use of the following tools to verify the codebase while you work:
53
53
54
54
-`pre-commit`: run `pre-commit install` in your command line to load inbuilt checks that will run every time you commit your changes.
55
-
The checks are: 1. check no large files have been staged, 2. lint python files for major errors, 3. format python files to conform with the [PEP8 standard](https://peps.python.org/pep-0008/).
56
-
You can also run these checks yourself at any time to ensure staged changes are clean by calling `pre-commit`.
55
+
The checks are: 1. check no large files have been staged, 2. lint python files for major errors, 3. format python files to conform with the [PEP8 standard](https://peps.python.org/pep-0008/).
56
+
You can also run these checks yourself at any time to ensure staged changes are clean by calling `pre-commit`.
57
57
-`pytest` - run the unit test suite and check test coverage.
58
58
59
-
{%- if cookiecutter.create_jupyter_notebook_directory|lower == "y" %}
59
+
{% if cookiecutter.create_jupyter_notebook_directory|lower == "y" -%}
60
60
!!! note
61
61
62
62
If you already have an environment called `{{ cookiecutter.repository_name }}` on your system (e.g., for a stable installation of the package), you will need to [chose a different environment name][choosing-a-different-environment-name].
@@ -67,9 +67,9 @@ You can also run these checks yourself at any time to ensure staged changes are
67
67
68
68
The following options allow you to strip down the test suite to the bare essentials:
69
69
70
-
{%- if cookiecutter.create_jupyter_notebook_directory|lower == "y" %}
70
+
{% if cookiecutter.create_jupyter_notebook_directory|lower == "y" -%}
71
71
1. The test suite includes unit tests and integration tests (in the form of jupyter notebooks found in the `examples` directory).
72
-
The integration tests can be slow, so if you want to avoid them during development, you should run `pytest tests/`.
72
+
The integration tests can be slow, so if you want to avoid them during development, you should run `pytest tests/`.
73
73
{%- endif %}
74
74
1. You can avoid generating coverage reports, by adding the `--no-cov` argument: `pytest --no-cov`.
75
75
@@ -84,9 +84,9 @@ The integration tests can be slow, so if you want to avoid them during developme
84
84
If you are running on a UNIX device (i.e., **not*- on Windows), you can test whether any changes you have made adversely impact memory and time performance as follows:
85
85
86
86
1. Install [memray](https://bloomberg.github.io/memray/index.html) in your `{{ cookiecutter.repository_name }}` conda environment: `conda install memray pytest-memray`.
87
-
2. Run the memory profiling integration test: `pytest -p memray -m "high_mem" --no-cov`.
88
-
3. Optionally, to visualise the memory allocation, run `pytest -p memray -m "high_mem" --no-cov --memray-bin-path=[my_path] --memray-bin-prefix=[my_prefix]` - where you must define `[my_path]` and `[my_prefix]` - followed by `memray flamegraph [my_path]/[my_prefix]-tests-test_100_memory_profiling.py-test_mem.bin`.
89
-
You will then find the HTML report at `[my_path]/memray-flamegraph-[my_prefix]-tests-test_100_memory_profiling.py-test_mem.html`.
87
+
1. Run the memory profiling integration test: `pytest -p memray -m "high_mem" --no-cov`.
88
+
1. Optionally, to visualise the memory allocation, run `pytest -p memray -m "high_mem" --no-cov --memray-bin-path=[my_path] --memray-bin-prefix=[my_prefix]` - where you must define `[my_path]` and `[my_prefix]` - followed by `memray flamegraph [my_path]/[my_prefix]-tests-test_100_memory_profiling.py-test_mem.bin`.
89
+
You will then find the HTML report at `[my_path]/memray-flamegraph-[my_prefix]-tests-test_100_memory_profiling.py-test_mem.html`.
90
90
91
91
All together:
92
92
@@ -114,8 +114,8 @@ Here are some use-cases that you may come across in which you are considering up
114
114
115
115
Add a Markdown file to the top-level in `docs`, e.g. `docs/my-page.md`.
116
116
Then, add a reference to that file within the `nav` key in `mkdocs.yml`, e.g.:
117
-
```yaml
118
117
118
+
```yaml
119
119
nav:
120
120
- Home: index.md
121
121
- Installation: installation.md
@@ -125,11 +125,14 @@ Here are some use-cases that you may come across in which you are considering up
125
125
126
126
You can also just rely on your document header to define the name in the navigation:
127
127
`my-page.md`
128
+
128
129
```md
129
130
# My Page
130
131
...
131
132
```
133
+
132
134
`mkdocs.yml`
135
+
133
136
```yaml
134
137
nav:
135
138
...
@@ -195,7 +198,7 @@ It uses [Pa11y](https://pa11y.org/) to test each page, providing a report where
195
198
If you find that your documentation has issues, here are some possible ways to resolve them:
196
199
197
200
- Many issues come from the translation of markdown files to HTML.
198
-
If these issues are blockers, you should raise them in the upstream [MkDocs-Material](https://github.com/squidfunk/mkdocs-material/issues) repository.
201
+
If these issues are blockers, you should raise them in the upstream [MkDocs-Material](https://github.com/squidfunk/mkdocs-material/issues) repository.
199
202
- If issues are not blockers (e.g. an unlabelled hyperlink that is not available to any user, irrespective of their accessibility constraints), then you can add them to the `.pallyci` configuration file [`ignore` list](https://github.com/pa11y/pa11y?tab=readme-ov-file#ignore-array) or [`hideElements` string](https://github.com/pa11y/pa11y?tab=readme-ov-file#hideelements-string).
200
203
- If you can solve the issue by updating the documentation configuration (e.g. colour scheme contrast levels, font sizes), then you can test using Pa11y locally before you push online as follows (A local [Node.js installation](https://nodejs.org/en/download/package-manager) is required):
201
204
@@ -207,7 +210,7 @@ If these issues are blockers, you should raise them in the upstream [MkDocs-Mate
207
210
208
211
The results will be printed to the console and will be available as a navigable set of HTML pages at `reports/pa11y/index.html`.
209
212
- If you are still unsure what part of the documentation an issue is referring to since it referencing HTML classes/ids etc., rather than Markdown files, then we recommend using the inbuilt accessibility checkers available in most common browsers.
210
-
First, serve your documentation locally, then use e.g., the [Mozilla Firefox accessibility inspector](https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/) to check for issues.
213
+
First, serve your documentation locally, then use e.g., the [Mozilla Firefox accessibility inspector](https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/) to check for issues.
1. Install the {{ cookiecutter.package_name }} package into the environment, ignoring dependencies (we have dealt with those when creating the conda environment): `pip install --no-deps .`
0 commit comments