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.
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:
There are multiple test environments, the default environments include:
Run tests in Python 3.7 with latest release of Sphinx
Run tests in Python 3.8 with latest release of Sphinx
Run mypy (type annotations checker) against latest release of Sphinx
Run linters, such as flake8 and Sphinx linkcheck.
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:
This is particularly useful for running a single test module (provide the test module’s path as an argument to the
Documentation is built with Sphinx:
tox -e docs
The HTML output is located in the
To check links:
tox -e docs-lint
Updating the change log#
Each pull request should update the change log (
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.
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.
Follow the LSST DM User Documentation Style Guide, which is primarily based on the Google Developer Style Guide.
Document the Python API with numpydoc-formatted docstrings. See the LSST DM Docstring Style Guide.
Follow the LSST DM ReStructuredTextStyle Guide. In particular, ensure that prose is written one-sentence-per-line for better Git diffs.