If you find errors, omissions, inconsistencies, or other things that need improvement, please create an issue. If you would like to add new functionality create a merge request . Contributions are always welcome!
Instead of installing the latest release from PyPI with pip, you should get the newest development version from Github:
git clone git@github.com:audeering/sphinx-apipages.git cd sphinx-apipages # Use virtual environment pip install -r requirements.txt
This way, your installation always stays up-to-date, even if you pull new changes from the Gitlab repository.
We follow the PEP8 convention for Python code and use ruff as a linter and code formatter. In addition, we check for common spelling errors with codespell. Both tools and possible exceptions are defined in :file:`pyproject.toml`.
The checks are executed in the CI using pre-commit. You can enable those checks locally by executing:
pip install pre-commit # consider system wide installation pre-commit install pre-commit run --all-files
Afterwards ruff and codespell are executed every time you create a commit.
You can also install ruff and codespell and call it directly:
pip install ruff codespell # consider system wide installation ruff check --fix . # lint all Python files, and fix any fixable errors ruff format . # format code of all Python files codespell
It can be restricted to specific folders:
ruff check sphinx-apipages/ tests/ codespell sphinx-apipages/ tests/
If you make changes to the documentation, you can re-create the HTML pages using Sphinx. You can install it and a few other necessary packages with:
pip install -r requirements.txt pip install -r docs/requirements.txt
To create the HTML pages, use:
python -m sphinx docs/ build/sphinx/html -b html
The generated files will be available in the directory build/sphinx/html/
.
It is also possible to automatically check if all links are still valid:
python -m sphinx docs/ build/sphinx/linkcheck -b linkcheck
You'll need pytest for that. It can be installed with:
pip install -r tests/requirements.txt
To execute the tests, simply run:
python -m pytest
pytest is configured inside :file:`pyproject.toml`.
New releases are made using the following steps:
- Update
CHANGELOG.rst
- Commit those changes as "Release X.Y.Z" with a pull request
- Create an (annotated) tag with
git tag -a vX.Y.Z
- Push the commit and the tag to Gitlab