Contributing to the docs

This documentation is open source. Rubin Observatory welcomes contributions that make this documentation more useful and accurate.

Keep in mind that everyone participating in this project is expected to follow the Rubin Observatory LSST Data Management Team Culture and Conduct Standards.

Raising an issue

If you spot an issue with the documentation, the best thing to do is raise a GitHub issue in the nb_lsst_io repo. Include any relevant URLs with your issue description.

If you need help with the Notebook Aspect, in general, reach out on one of our support channels first.

Creating a pull request

You can contribute directly to the nb_lsst_io repo by creating a pull request. If you’re intending to make a substantial change, it’s a good idea to create a GitHub issue first with your proposal. Rubin Observatory can’t accept contributions that don’t fit with our strategy and roadmap.

These sections can help you create a successful pull request:

Editing the docs locally

Setting up the development environment

These are the basic steps to clone and build the docs:

git clone https://github.com/lsst-dm/nb_lsst_io
cd nb_lsst_io

Next, create a Python virtual environment (with venv, for example).

Once you’ve done that, initialize the development environment:

make init

This command installs tox and pre-commit hooks. Tox enables you to build customized documentation sites for each RSP environment from a single source repository. A consequence of using tox is that you don’t install and run Sphinx directly; instead, tox handles build dependencies through its own Python virtual environments. If you ever need to refresh those virtual environments — perhaps because you’ve updated your branch and the up-stream dependencies changed — you can re-initialize the environment by running make init in your shell again.

Running a documentation build

Build documentation for all RSP environments by running tox:

tox

By default, the tox command generates documentation site builds for each RSP environment in the _builds/html directory. For example, _builds/html/idfprod/index.html is the homepage for the production IDF deployment and _builds/html/summit/index.html is the homepage for the summit deployment.

To build documentation for a limited number of environments, supply environment names to tox’s -e option:

tox -e sphinx-idfprod,sphinx-summit

To see a list of all available environments:

tox -a

Although GitHub Actions performs link checks automatically for you, you can manually check links:

tox -e linkcheck-idfprof

To force a complete rebuild of the documentation, you can clean-up the existing builds:

make clean

Git commit hooks

To ensure that code quality is consistent, this project uses pre-commit hooks to lint the source repository before every commit. These hooks are also in GitHub Actions, however, for the best development experience you will want to run these hooks during development. By running make init, these hooks are installed in your local repository clone.

If the hooks “fail,” you will need to correct and re-add (git add) your changes before running git commit again. Some hooks auto-correct the source, in which case you only need to re-add the changes.

Documentation style guide

This documentation is written in reStructuredText. The DM reStructuredText style guide can help you create effective reStructuredText.

Style and voice

This is user documentation, which is different from academic writing. Here are some tips:

  • Make sure that all of your writing is in the service of users.

  • Write with the active voice and in the present tense as much as possible.

  • Address the user directly (“you can…”). Never use “we” since that’s ambiguous. If “we” means “Rubin Observatory,” then name “Rubin Observatory.” If “we” means the user, then say “you.” Even in tutorials, don’t use “we” to refer to an imaginary writer assisting the user.

  • Write simply, with short sentences and short paragraphs. Chunk information with headers.

  • Write confidently and precisely, yet also casually. Contractions are good.

For further discussion about specific style issues, refer to the Google Developer Documentation Style Guide.

File names

Always use hyphens to separate words in file names. Don’t use underscores or spaces.

Prose formatting in plain text

DM’s user documentation is written with soft wrapping, meaning that lines are as long as they need to be in the plain text file and the text editor is expected to handle wrapping. Never hard wrap to an arbitrary line length. Soft wrapping makes editing more approachable for more people (particularly those using the GitHub editor) and makes pull request line comments more useful.

More specifically, use semantic line formatting. Generally this means that each sentence should be its own line in the text file.

Titles and headings

Use sentence case for headings (don’t use title case). Capitalize proper nouns as usual.

Try not to use more than two levels of heading hierarchy. Using more than two levels of hierarchy might suggest an information architecture issue.

Also keep in mind DM’s reStructuredText heading styles.

Environment-specific documentation

If the content is specific to an RSP environments, or is different across RSP environments, use the project’s tools to write environment-specific content. See Writing environment-specific documentation.