|
| 1 | +# Infrastructure |
| 2 | + |
| 3 | +## Tests |
| 4 | + |
| 5 | +Write your test methods and classes in the `test` folder. We are using [pytest](https://docs.pytest.org/en/7.2.x/getting-started.html). |
| 6 | +In your test module you can call your methods in a simple way: |
| 7 | + |
| 8 | +```python |
| 9 | +# filename: test_math.py |
| 10 | +from my_awesome_software import math |
| 11 | + |
| 12 | +# here your test function |
| 13 | +``` |
| 14 | + |
| 15 | +If you're testing a small piece of code, make it a unit test. If you want to test whether two or more software units work well together, create an integration test. |
| 16 | + |
| 17 | +:::{important} |
| 18 | +Before committing your changes |
| 19 | +::: |
| 20 | + |
| 21 | +### Run the tests |
| 22 | + |
| 23 | +Be sure that you have installed pytest and run it |
| 24 | +```bash |
| 25 | +pip install pytest |
| 26 | +pytest |
| 27 | +``` |
| 28 | +You should also see coverage information. |
| 29 | + |
| 30 | +### Install your package locally |
| 31 | + |
| 32 | +For a local, editable install, in the project directory, run: |
| 33 | +```bash |
| 34 | +pip install -e . |
| 35 | +``` |
| 36 | + |
| 37 | +For a local, editable install with all the development tools (e.g. testing, formatting etc.) run: |
| 38 | +```bash |
| 39 | +pip install -e '.[dev]' |
| 40 | +``` |
| 41 | + |
| 42 | +You might want to install your package in an _ad hoc_ environment. |
| 43 | + |
| 44 | +To test if the installation works, try to call your modules with python in another folder from the same environment. |
| 45 | +```python |
| 46 | +from my_awesome_sofware.math import add_two_integers |
| 47 | +add_two_integers(1, 2) |
| 48 | +``` |
| 49 | + |
| 50 | +# Pre-commit hooks |
| 51 | + |
| 52 | +Running `pre-commit install` will set up [pre-commit hooks](https://pre-commit.com/) to ensure the code is |
| 53 | +formatted correctly. Currently, these are: |
| 54 | +* [ruff](https://github.com/charliermarsh/ruff) does a number of jobs, including linting, auto-formatting code (with `ruff-format`), and sorting import statements. |
| 55 | +* [mypy](https://mypy.readthedocs.io/en/stable/index.html) a static type checker |
| 56 | +* [check-manifest](https://github.com/mgedmin/check-manifest) to ensure that the right files are included in the pip package. |
| 57 | +* [codespell](https://github.com/codespell-project/codespell) to check for common misspellings. |
| 58 | + |
| 59 | + |
| 60 | +These will prevent code from being committed if any of these hooks fail. To run them individually: |
| 61 | +```sh |
| 62 | +ruff check --fix # Lint all files in the current directory, and fix any fixable errors. |
| 63 | +ruff format # Format all files in the current directory. |
| 64 | +mypy -p my_awesome_software |
| 65 | +check-manifest |
| 66 | +codespell |
| 67 | +``` |
| 68 | + |
| 69 | +You can also execute all the hooks using |
| 70 | +```sh |
| 71 | +pre-commit run |
| 72 | +``` |
| 73 | +or |
| 74 | +```sh |
| 75 | +pre-commit run --all-files |
| 76 | +``` |
| 77 | + |
| 78 | + The best time to run this is after you have staged your changes, but before you commit them. |
| 79 | + |
| 80 | +In the case you see `mypy` failing with an error like `Library stubs not installed for this-package`, you do have to edit the `.pre-commit-config.yaml` file by adding the additional dependency to `mypy`: |
| 81 | +``` sh |
| 82 | +- id: mypy |
| 83 | + additional_dependencies: |
| 84 | + - types-setuptools |
| 85 | + - types-this-package |
| 86 | +``` |
| 87 | + |
| 88 | +# Versioning |
| 89 | + |
| 90 | +We recommend the use of [semantic versioning](https://semver.org/), which uses a `MAJOR`.`MINOR`.`PATCH` versiong number where these mean: |
| 91 | + |
| 92 | +* PATCH = small bugfix |
| 93 | +* MINOR = new feature |
| 94 | +* MAJOR = breaking change |
| 95 | + |
| 96 | +## Automated versioning |
| 97 | +[`setuptools_scm`](https://github.com/pypa/setuptools_scm) can be used to automatically version your package. It has been pre-configured in the `pyproject.toml` file. [`setuptools_scm` will automatically infer the version using git](https://github.com/pypa/setuptools_scm#default-versioning-scheme). To manually set a new semantic version, create a tag and make sure the tag is pushed to GitHub. Make sure you commit any changes you wish to be included in this version. E.g. to bump the version to `1.0.0`: |
| 98 | + |
| 99 | +```sh |
| 100 | +git add . |
| 101 | +git commit -m "Add new changes" |
| 102 | +git tag -a v1.0.0 -m "Bump to version 1.0.0" |
| 103 | +git push --follow-tags |
| 104 | +``` |
| 105 | +:::{tip} |
| 106 | +It is also possible to perform this step by using the [GitHub web interface or CLI](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository). |
| 107 | +::: |
| 108 | + |
| 109 | +# GitHub actions workflow |
| 110 | + |
| 111 | +A GitHub actions workflow (`.github/workflows/test_and_deploy.yml`) has been set up to run (on each commit/PR): |
| 112 | +* Linting checks (pre-commit). |
| 113 | +* Testing (only if linting checks pass) |
| 114 | +* Release to PyPI (only if a git tag is present and if tests pass). Requires `TWINE_API_KEY` from PyPI to be set in repository secrets. |
| 115 | + |
| 116 | +This automation ensures that each commit or pull request is validated and that releases are published only when all checks pass. |
| 117 | + |
| 118 | +# Documentation |
| 119 | + |
| 120 | +Software documentation is important for effectively communicating how to use the software to others as well as to your future self. |
| 121 | + |
| 122 | +If you want to include documentation in your package, make sure to respond with `1 - Yes` when prompted during the `cookiecutter` setup. This will instantiate a `docs` folder with a skeleton documentation system, that you can build upon. |
| 123 | + |
| 124 | +The documentation source files are located in the `docs/source` folder and should be written in either [reStructuredText](https://docutils.sourceforge.io/rst.html) or [markdown](https://myst-parser.readthedocs.io/en/stable/syntax/typography.html). The `index.rst` file corresponds to the main page of the documentation website. Other `.rst` or `.md` files can be included in the main page via the `toctree` directive. |
| 125 | + |
| 126 | +The documentation is built using [Sphinx](https://www.sphinx-doc.org/en/master/) and the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/). The `docs/source/conf.py` file contains the `Sphinx` configuration. |
| 127 | + |
| 128 | +## Building the documentation locally |
| 129 | +You can build and view the documentation website locally, on your machine. To do so, run the following commands from the root of your project: |
| 130 | + |
| 131 | +```sh |
| 132 | +# Install the documentation build dependencies |
| 133 | +pip install -r docs/requirements.txt |
| 134 | +# Build the documentation |
| 135 | +sphinx-build docs/source docs/build |
| 136 | +``` |
| 137 | +This should create a `docs/build` folder. You can view the local build by opening `docs/build/index.html` in a browser. |
| 138 | +To refresh the documentation, after making changes, remove the `docs/build` folder and re-run the above command: |
| 139 | + |
| 140 | +```sh |
| 141 | +rm -rf docs/build |
| 142 | +sphinx-build docs/source docs/build |
| 143 | +``` |
| 144 | + |
| 145 | +## Publishing the documentation |
| 146 | +We have included an extra GitHub actions workflow in `.github/workflows/docs_build_and_deploy.yml` that will build the documentation and deploy it to [GitHub pages](https://pages.github.com/). |
| 147 | +* The build step is triggered every time a pull request is opened or a push is made to the `main` branch. This way you can make sure that the documentation does not break before merging your changes. |
| 148 | +* The deployment is triggered only when a tag is present (see [Automated versioning](#automated-versioning)). This ensures that new documentation versions are published in tandem with the release of a new package version on PyPI (see [GitHub actions workflow](#github-actions-workflow)). |
| 149 | +* The published docs are by default hosted at `https://<github_username_or_organization>.github.io/<package_name>/`. To enable hosting, you will need to go to the settings of your repository, and under the "Pages" section, select the `gh-pages` branch as the source for your GitHub pages site. |
| 150 | +* A popular alternative to GitHub pages for hosting the documentation is [Read the Docs](https://readthedocs.org/). To enable hosting on Read the Docs, you will need to create an account on the website and follow the instructions to link your GitHub repository to your Read the Docs account. |
| 151 | + |
| 152 | +## Docstrings and API documentation |
| 153 | +The journey towards good documentation starts with writing docstrings for all functions in your module code. In the example `math.py` and `greetings.py` modules you will find some docstrings that you can use as a template. We have written the example docstrings following the [numpy style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html) but you may also choose another widely used style, such as the [Google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). |
| 154 | + |
| 155 | +Once you have written docstrings for all your functions, API documentation can be automatically generated via the [Sphinx autodoc extension](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html). We have given examples of how to do this in the `docs/source/api_index.rst` file. |
0 commit comments