Contributing to the documentation#

This documentation is a Sphinx project hosted out of the docs directory of the phalanx repository on GitHub. You can contribute to this documentation by editing the source files in a clone of this repository and submitting a pull request on GitHub. This page provides the basic steps.

Set up for documentation development#

Cloning phalanx#

Start by cloning Phalanx into your own editing environment. Members of the lsst-sqre/phalanx repository on GitHub can clone the repository directly and create a ticket branch, per the Data Management workflow guide. Otherwise, fork lsst-sqre/phalanx following GitHub’s guide.

Set up pre-commit#

Phalanx uses Pre-commit to lint files and, in some cases, automatically reformat files. Follow the instructions in Setting up pre-commit linting and helm-docs generation.

Initialize the development environment#

From the phalanx directory, initialize your environment:

make init

This steps installs tox, the tooling for builds with isolated Python environments, and pre-commit, a tool for linting and formatting files (see Setting up pre-commit linting and helm-docs generation).

Compiling the documentation#

Use the tox docs environment for compiling the documentation:

tox -e docs

The built documentation is located in the docs/_build/html directory.

Sphinx caches build products and in some cases you may need to delete the build to get a consistent result:

make clean

Submitting a pull request and sharing documentation drafts#

Members of the lsst-sqre/phalanx repository should submit pull requests following the Data Management workflow guide. Note that GitHub Actions builds the documentation and uploads a draft edition of the documentation to the web. You can find your branch’s development edition at https://phalanx.lsst.io/v.

If you are submitting a GitHub pull request from a fork, the documentation will build as a check, however the draft won’t upload for public staging.

More information on writing documentation#

When writing documentation for Rubin Observatory, refer to our Documentation Style Guide, based on the Google Documentation Style Guide, for guidelines on writing effective documentation content.

For technical tips on writing Sphinx documentation, see the reStructuredText Style Guide and Documenteer’s documentation for User guides.