Developing¶

This project makes use of tox to manage running tests and other tasks. The tests can be divided into three categories: checks, unit tests and regression (integration) tests. tox.ini defines “environments” that configure these tasks. Each of these are described in the next section. The unit and regression tests make use of pytest.

The repository includes a Poetry pyproject.toml file to help you set up a virtual environment with tox and other development dependencies. From the repository checkout root directory execute:

poetry install

Poetry will create a virtual environment in .venv, which you can activate like this1:

source .venv/bin/activate

Now tox is available for running the tests. Starting tox without any arguments will run the check, unit and regression environments. Refer to the next section for an overview of all environments.

1: If you install direnv, the virtual environment can be automatically activated when you enter the rinohtype repository checkout (see the .envrc file).

Tox Environments¶

The following environments execute unit tests and regression tests:

unit: Runs the unit tests.
regression: Runs integration/regression tests. Each of these tests render a tiny document (often a single page) focusing on a specific feature, which means they also execute quickly. Their PDF output is compared to a reference PDF that is known to be good.
longrunning (not maintained, broken): Runs regressions tests that render larger documents. These tests take several minutes to complete.

The other environments run checks, build documentation and build “binary” distributions for Mac and Windows:

check: Performs basic checks; just poetry check at this point.
check-docs: Perform checks on the documentation source files using doc8 and sphinx-doctest. restview can be useful when fixing syntax errors in README.rst, CHANGES.rst, …
build-docs: Build the rinohtype documentation using Sphinx, both in HTML and PDF formats.
macapp (not maintained, broken?): Build a stand-alone macOS application bundle using briefcase. This task can only be run on macOS.
wininst (not maintained, broken?): Build a stand-alone rinohtype installer for the Windows platform with the help of pynsist. This task also can be run on other platforms than Windows.

Customization settings for doc8 and pytest are stored in setup.cfg.

Testing against multiple Python interpreter versions¶

Tox facilitates running tests on multiple Python interpreter versions. You can combine the test environment names with a factor to execute them on a specific Python interpreter version. For example, to run the unit tests on CPython 3.8:

tox -e unit-py38

While it is typically sufficient to test on a single Python version during development, it can be useful to run tests on a set of Python versions before pushing your commits. Of course, this requires these versions to be available on your machine. It is highly recommended you use pyenv (or pyenv-win) to install and manage these. For example, to install CPython 3.8.1, you can run:

pyenv install 3.8.1

and pyenv will download, build and install this version of CPython for you. pyenv will install the different Python versions in an isolated location (typically under ~/.penv), so they will not interfere with your system-default Python versions.

The file .python-version in the root of the repository specifies which Python versions pyenv should make available whenever we are inside the repository checkout directory. The file lists specific the versions of CPython rinohtype aims to support plus recent PyPy3 versions (ideally, we should closely track the latest releases). The pyenv_install.py script can install these for you (skipping any that are already installed).

Continuous integration¶

GitHub Actions automatically executes the tox environments when new commits are pushed to the repository. The tox environments are run on Linux, macOS and Windows, and run the tests on an array of Python versions to make sure that we don’t break any corner cases. See .github/workflows for details.

Making a release¶

This is a list of steps to follow when making a new release of rinohtype. Publishing the new release to PyPI and uploading the documentation to GitHub Pages is handled by the GitHub Actions workflow.

Make sure your checkout is clean.

Run run tests and checks locally:

tox -e check,check-docs,build-docs,unit,regression

Push your commits to master on GitHub. Don’t create a tag yet!
Check whether all tests on GitHub Actions are green.
Set the release date.
- set __release_date__ in src/rinoh/__init__.py (YYYY-MM-DD)
- add release date to this release’s section (see other sections for examples)
Create a git tag: git tag v$(poetry version --short)
Push the new tag: git push origin v$(poetry version --short)
The GitHub workflow will run all tox environments and upload the new version to PyPI if all checks were successful.
Create a new release on GitHub. Include the relevant section of the changelog. Use previous releases as a template.
- Tag version: the release’s tag vx.y.z
- Release title: Release x.y.z (date)
- Add a link to the release on PyPI:
```
Install from [PyPI](https://pypi.org/project/rinohtype/x.y.z/)
```
- Copy the release notes from the change log
Bump version number and reset the release date to “upcoming”.
- poetry version patch # or 'minor'
- add new section at the top of the changelog
- set __release_date__ in src/rinoh/__init__.py to 'upcoming'