Development guide

This page provides procedures and guidelines for developing and contributing to Documenteer.

Scope of contributions

Documenteer is an open source package, meaning that you can contribute to Documenteer itself, or fork Documenteer for your own purposes.

Since Documenteer is intended for internal use by Rubin Observatory, community contributions can only be accepted if they align with the Rubin Observatory’s aims. For that reason, it’s a good idea to propose changes with a new GitHub issue before investing time in making a pull request.

Documenteer is developed by the SQuaRE team. The lead developer and maintainer is Jonathan Sick.

Environment set up

To develop Documenteer, create a virtual environment with your method of choice (like virtualenvwrapper) and then clone or fork, and install:

git clone https://github.com/lsst-sqre/documenteer.git
cd documenteer
make init

Code formatting and linting with pre-commit

Documenteer uses pre-commit to automatically and consistently format and lint the codebase on each commit. By running make init, pre-commit is already installed in your environment.

If pre-commit “fails” because the black or isort code formatters changed the source, simply git add the changes and try the commit again.

To learn more about the pre-commit configuration, see the .pre-commit-config.yaml file in the repository.

Running tests via tox

The best way to run tests is through tox, which is pre-installed through the make init command:

tox

There are multiple test environments, the default environments include:

Default tox environments

Enviroment

Description

py37-test-sphinxlatest

Run tests in Python 3.7 with latest release of Sphinx

py38-test-sphinxlatest

Run tests in Python 3.8 with latest release of Sphinx

typing-sphinxlatest

Run mypy (type annotations checker) against latest release of Sphinx

lint

Run linters, such as flake8 and Sphinx linkcheck.

coverage-report

Aggregates unit test coverage reports from individual “test” runs and displays a report.

It is also possible to run individual tox environments, for example:

tox -e typing-sphinxlatest

Additional tox environments are available for testing against different versions of Sphinx. For example, to test against Sphinx 2.3.x, run:

tox -e py37-test-sphinx23

To learn more about the available tox environments, review the tox.ini file in the code repository.

Running tests through pytest

Although tox is the recommended method for running tests, it is still possible to run tests directly through pytest:

pytest

This is particularly useful for running a single test module (provide the test module’s path as an argument to the pytest command).

Building documentation

Documentation is built with Sphinx:

tox -e docs

The HTML output is located in the docs/_build/html directory.

To check links:

tox -e docs-lint

Updating the change log

Each pull request should update the change log (CHANGELOG.rst). Add a description of new features and fixes as list items under a section at the top of the change log called “Unreleased:”

Unreleased
----------

- Description of the feature or fix.

If the next version is known (because Documenteer’s master branch is being prepared for a new major or minor version), the section may contain that version information:

X.Y.0 (unreleased)
------------------

- Description of the feature or fix.

If the exact version and release date is known (because a release is being prepared), the section header is formatted as:

X.Y.0 (YYYY-MM-DD)
------------------

- Description of the feature or fix.

Style guide

Code

  • Code formatting is performed automatically through black and isort. Generally this means that the code base automatically conforms to PEP 8 and will pass the flake8 linter.

  • Write tests for Pytest.

  • Use PEP 484 type annotations wherever possible, especially for new code.

  • Use Click for command-line interfaces.

Documentation