Contributing to Observatory Operations Documentation

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

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

Raising an Issue

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

Creating a Pull Request

You can contribute directly to the observatory-ops-docs 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:

• Building the Documentation Locally
• Documentation Style Guide

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-ops-docs
   cd nb_lsst_io
   

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-ops.lsst.io/v/. You can push to a branch you’ve created at any time.

The master branch is always published as https://obs-ops.lsst.io. Only authorized individuals can merge to master (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
   • 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 master.
6. Notify Patrick Ingraham the PR was merged.
7. Notify the authorized individual to tag the release.

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.

• reStructuredText Introductory and Tutorial Material and references therein.
• reStructuredText Primer
• reStructuredText Quick Reference
• reStructuredText Primer from Sphinx
• reStructuredText Style Guide for Rubin Observatory Data Management Developers

The repository style guide will help you content for this site.