Replace the heading above with your_package
.
- Hit "Use this template" in the top right of this page
- Work through as much of the basic, intermediate and advanced steps as you like.
- Edit this README and make sure you update
your_package
,your_name
andlicence_type
.
Nothing helps as much as examples.
- This is a great guide that provides a brief overview of all the tools we use in this template.
- All of the tooling has been implemented in
ispypsa
- Choose a license, and add the
LICENSE
file to the repo - Update your code of conduct
- Update the Get Started! section of the contributing guidelines
- Note that this currently has steps you would use to install various dependency groups that are being used by
nemseer
- Note that this currently has steps you would use to install various dependency groups that are being used by
- (Optional) Make your software citeable
UV is used for dependency management, dependency resolution and can also be used as a build tool.
- Install
uv
- Edit the project info in
pyproject.toml
, or delete it and useuv init
to start from scratch (if you are proceeding to the next few sections, it is best not to delete the existigpyproject.toml
) - You can add dependencies in the
pyproject.toml
or use the command line:- You can add a core dependency via
uv add
, e.g.uv add pandas
- You can add dependencies to a group (adding to a group is optional) using
uv add pytest --group test
- You can install the dependencies from
uv.lock
, including optional groups, usinguv sync --group test
- You can update dependencies and create a
uv.lock
file usinguv lock
- You can add a core dependency via
- Run scripts with
uv run
- Commit
uv.lock
to version control
- Edit the project info in
- To install testing dependencies, use
uv sync
as this install dev dependencies by default. - Put your tests in
tests/
- Run your tests by running
pytest
(uv run pytest
) in the project directory - Test coverage will be in
tests/htmlcov/index.html
Because code shouldn't look awful. We will be using isort
(import sorting), flake8
(python linter) and black
(an autoformatter) via pre-commit
.
pre-commit
streamlines creating pre-commit hooks, which are run prior to a commit being accepted by git (locally). This way, your code won't be committed if there are style issues (some of which will be automatically addressed, after which you must stage any further changes).
- Install the required packages using
uv run pre-commit install
- (Optional) Configure any additional pre-commit hooks in the YAML
- To run manually, you can run
uvx ruff check --fix
anduvx ruff format
. Alternatively, these hooks will run as you try and commit changes
Both of these can be achieved via GitHub Actions.
Note that some testing config is specified in the pyproject.toml
.
- The workflow is located here.
- Automatically runs linting and autoformatting as above
- If that passes, then runs your code tests across Mac and Ubuntu for a couple of Python versions
- If a GitHub release is created based on a Git tag, it will build the package and upload to PyPI
- To get this to work, you will need to setup your github repository as trusted publisher
- Uncomment the lines specified. This should allow the workflow to run on a push, pull-request or when manually triggered. Note that publishing to PyPI is only triggered on a release
- Activate the workflow. Do this by navigating to the Actions tab, selecting
...
and activating it.
If you've made it this far, well done. Prepare for the most tricky bit: documentation
This section is a WIP. We will add to it as we come across good resources.
Documentation is located in the docs folder.
This project uses:
- Sphinx to generate documentation. Sphinx is based on reStructuredText.
- We use several Sphinx extensions that make using Sphinx easier
- Sphinx is configured in
conf.py
- MyST, a parser which optionally lets you write your documentation using Markdown. If you know Markdown, this can reduce, but not eliminate, the need for reStructuredText.
- readthedocs to host our documentation online. You'll need to link RtD to your repo (see here). Settings can be configured in the YAML
If you make changes to your docs, successfully build it locally (see below) or on RtD and then see that no change has been made, your browser may be caching the old version of the docs. Clear your browser cache and then try again.
First, install the packages required for buildings docs using uv sync
You can test whether your documentation builds locally by using the commands offered by the Makefile. To do this, change directory to docs
and run make
to see build options. The easiest option is make html
.
There is a fair bit to learn to be able to write docs. Even if you use MyST, you will need to learn about roles and directives.
Here are some tutorials:
The source folder in this template repo contains basics for making docs. There is also an example of the markdown file used to generate the API section of the nemseer
docs.
You can also refer to:
pytest
,isort
andmypy
(not included) can be configured in the pyproject.toml- See relevant sections above for config for
pre-commit
,read-the-docs
and Sphinx
Interested in contributing? Check out the contributing guidelines, which also includes steps to install your_package
for development.
Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.
your_package
was created by your_name
. It is licensed under the terms of the licence_type
.
This template was created using cookiecutter
, the py-pkgs-cookiecutter
template and using Marwan Debbiche's excellent walkthrough