Contributing to Observatory Controls Documentation

Below are instructions and guidelines on contributing to the Rubin Observatory Controls Documentation. This documentation is built with Sphinx and published to https://obs-controls.lsst.io.

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

Keep in mind that everyone participating in this project is expected respectful to others. The Team Culture and Conduct Standards provides an example of what is expected when participating to Rubin documentation.

Raising an issue

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

Creating a Pull Request

You can contribute directly to the Rubin Observatory Controls Documentation repo by creating a pull request. If you are intending to make a substantial change, it is a good idea to create a GitHub issue first with your proposal. LSST cannot accept contributions that are not aligned with our strategy and roadmap.

These sections can help you create a successful pull request:

Building the Documentation Locally

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

  1. Clone the GitHub repository:

    git clone https://github.com/lsst-ts/observatory-controls-docs
cd observatory-controls-docs

  2. Create a Python virtual environment (with venv, for example):

    python3 -m venv .venv
source .venv/bin/activate

    Note

    Activate this virtual environment in another shell by re-running the source command.

  3. Install the Python dependencies:

    python -m pip install --upgrade pip
python -m pip install -r requirements.txt

  4. You are now able to edit the cloned repository. The remaining items below are commands used to build and validate the documentation. These commands must be executed from the top-level directory.

  5. Build the site:

    make html

    Note

    Open _build/html/index.html in a browser to review it.

  6. Validate the documentation build:

    make linkcheck

    Note

    If some links are behind a login, you might need to ignore them. Look at the linkcheck_ignore variable in conf.py for examples of how to do this.

  7. Completely clear the build:

    make clean

Deployment

Whenever you push to the GitHub repository, the site is built for the corresponding branch. Find your build at https://obs-controls.lsst.io/v/. You can push to a branch you’ve created at any time.

The main branch is always published as https://obs-controls.lsst.io. Only authorized individuals can merge to main (may be delegated). To incorporate your suggestions, create a pull request.

Approval Process

  1. Verify the content with all authors and contributors.
  2. Create a PR.
  3. Request the following to review the PR:
    • Patrick Ingraham
    • Any applicable Product Owner
  4. Respond to the comments received during the review process.
  5. After all reviewers approve, the submitter will squash commits and merge to main.

Documentation Style Guide

New to reStrcturedText and Sphinx

Check out these resources and guides. Sources files are available to compare raw reST and HTML outputs.