Welcome to rstcheck-sphinx’s documentation!

General
CI
PyPI
Github

This a the documentation of rstcheck-sphinx, a builder extension for the sphinx documentation generator to check the source with rstcheck.

Installation

This part of the documentation covers how to install the package. It is recommended to install the package in a virtual environment.

Create virtual environment

There are several packages/modules for creating python virtual environments. Here is a manual by the PyPA.

Installation from PyPI

You can simply install the package from PyPI:

$ pip install rstcheck-sphinx

Extras

rstcheck-sphinx has extras which can be installed to activate optional functionality:

• sphinx - To activate support for rst documents using the sphinx builder.

• toml - To activate support for TOML files as configuration files.

To install an extra simply add it in brackets like so:

$ pip install rstcheck-sphinx[sphinx,toml]

Installation from source

You can install rstcheck-sphinx directly from a Git repository clone. This can be done either by cloning the repository and installing from the local clone:

$ git clone https://github.com/rstcheck/rstcheck-sphinx
$ cd rstcheck-sphinx
$ pip install .

Or installing directly via git:

$ pip install git+https://github.com/rstcheck/rstcheck-sphinx

You can also download the current version as tar.gz or zip file, extract it and install it with pip like above.

Workflows

Here is the documentation about different workflows for rstcheck-sphinx.

Development

rstcheck-sphinx uses Semantic Versioning.

rstcheck-sphinx uses main as its single development branch. Therefore releases are made from this branch. Only the current release is supported and bugfixes are released with a patch release for the current minor release.

Tooling

For development the following tools are used:

• poetry for dependency management, package metadata, building and publishing.

• tox for automated and isolated testing.

• pre-commit for automated QA checks via different linters and formatters.

Set up Local Development Environment

The setup of a local development environment is pretty easy. The only tool you need is the poetry. You can install it via the recommended way, which installs it globally on your system or you can install it via pip in a self-created virtualenv (virtualenv manual).

With poetry set up and ready we can create our development environment in just one step:

$ poetry install

This will install rstcheck-sphinx along its main and development dependencies.

Working with the Local Development Environment

Dependency management and more with poetry

is used for dependency management, building and publishing rstcheck-sphinx.

Testing with tox

To run all available tests and check simply run:

$ tox

This will run:

• formatters and linters via pre-commit.

• the full test suite with pytest.

• a test coverage report.

• tests for the documentation.

Different environment lists are available and can be selected with tox -n <ENVLIST>:

• test: run full test suite with pytest and report coverage.

• py3.7 - py3.10 run full test suite with specific python version and report coverage.

• docs: run all documentation tests.

Linting and formatting pre-commit

can be used directly from within the development environment or you can use tox to run it pre-configured.

There are 3 available tox envs with all use the same virtualenv:

• pre-commit: For running any pre-commit command like tox -e pre-commit -- autoupdate --freeze.

• pre-commit-run: For running all hooks against the code base. A single hook’s id can be passed as argument to run this hook only like tox -e pre-commit-run -- black.

• pre-commit-install: For installing pre-commit hooks as git hooks, to automatically run them before every commit.

IDE integration

The development environment has flakeheaven (a flake8 wrapper), pylint and mypy installed to allow IDEs to use them for inline error messages. Their config is in pyproject.toml. To run them actively use pre-commit and/or tox.

Releases

Release workflow

When enough changes and additions or time important fixes have accumulated on the main branch its time for a new release. The exact time is subject to the judgment of the maintainer(s).

Note

Before starting the process of creating a new release make sure that all CI pipelines are green for the current commit.

1. Check if the CHANGELOG.md is up-to-date and all changes are noted.

2. Run prep_release.py script to bump version, finalize CHANGELOG.md, commit the changes and create a new git tag:

   $ python3 prep_release.py <TYPE>
   

   For the increase type there are three options:

   • patch / bugfix: for changes that do not add new functionality and are backwards compatible

   • minor / feature: for changes that do add new functionality and are backwards compatible

   • major / breaking: for changes that are not backwards compatible

3. Build the sdist and wheel:

   $ poetry build
   

4. Publish package:

   $ poetry publish
   

5. Push the commit and tag to github:

   $ git push --follow-tags
   

Changelog

This is the changelog of rstcheck-sphinx. Releases and their respective changes are listed here. The order of releases is time and not version based! For a list of all available releases see the tags section on Github. Links on the versions point to PyPI.

Unreleased

diff db97baa06901…main

• Initial release

Authors

Author

Christian Riedel <cielquan@protonmail.com>

Additional contributions by (sorted by name)

License

MIT License

Copyright (c) 2022 Christian Riedel

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.