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 LSST, community contributions can only be accepted if they align with LSST’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 LSST 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
pip install -e ".[dev,pipelines,technote]"

The dev extra includes test and documentation dependencies. You also need to install the pipelines and technote extras to ensure that all tests will run.

Running tests

Run pytest from the root of the source repository:

pytest

Pytest also runs code style linting (through pytest-flake8), coverage analysis (through pytest-coverage), and static type checking (through pytest-mypy).

The pytest command must succeed for a pull request to be accepted.

Building documentation

Documentation is built with Sphinx:

cd docs
make html

To clear the built output:

make clean

To check links:

make linkcheck

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

  • Follow PEP 8 for code style. Flake8 should detect any issues for you.

  • Write tests for Pytest.

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

  • Use Click for command-line interfaces.

Documentation