Contributing to Rubin Observatory Documentation for Data Preview 0.2 (DP0.2)¶
Below are instructions and guidelines on contributing to the Rubin Observatory Documentation for DP0.2. This documentation is built with Sphinx and published to https://dp0-2.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 dp0-2_lsst_io repo. Include any relevant URLs with your issue description.
Creating a pull request (PR)¶
You can contribute directly to the dp0-2_lsst_io repo by creating a pull request (PR). 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 PR:
Building the documentation locally¶
These are the basic steps to clone and build the docs:
Clone the GitHub repository:
git clone https://github.com/lsst/dp0-2_lsst_io cd dp0-2_lsst_io
Create a Python virtual environment (with venv, for example):
python3 -m venv .venv source .venv/bin/activate
Activate this virtual environment in another shell by re-running the
Install the Python dependencies:
python -m pip install --upgrade pip python -m pip install -r requirements.txt
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.
Build the site:
_build/html/index.htmlin a browser to review it.
Validate the documentation build:
If some links are behind a login, you might need to ignore them. Look at the
conf.pyfor examples of how to do this.
Completely clear the build:
An error will alert you of identical labels during the build process.
Whenever you push to the GitHub repository, the site is built for the corresponding branch. Find your build at https://dp0-2.lsst.io/v/. You can push to a branch you’ve created at any time.
main branch is always published as https://dp0-2.lsst.io. Only authorized individuals can merge to
main (may be delegated).
To incorporate your suggestions, create a pull request.
Verify the content with all authors and contributors.
Create a PR.
Request the following to review the PR (additional reviewers may be included in the process):
Respond to the comments received during the review process.
After all reviewers approve, the submitter will squash commits and merge to main.
Notify Melissa Graham or Leanne Guy the PR was merged.
Notify the authorized individual to tag the release.
Documentation style guide¶
New to reStructuredText and sphinx¶
Check out these resources and guides. Sources files are available to compare raw reST and HTML outputs.
Data products documentation style guide¶
- The information provided below is based on the LSST DM reStructuredText style guide.
A style guide specific to Data Previews will be provided at a later time.
The information below can help you create effective reStructuredText for the Rubin Observatory Documentation for DP0.2.
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 simple, short sentences in short paragraphs. Chunk information with headers.
Write confidently and precisely, yet also casually.
Always use hyphens to separate words in directory and file names. Do not use underscores or spaces. This choice is based on the Google Developer Documentation Style Guide for search engine optimization.
Use all-lowercase for directory names unless it is appropriate otherwise (such as a common acronym like LSST).
A template folder is located in the documentation project directory. It contains template pages for the Documentation for DP0.2, including a directory index. Review the README in the template folder for instructions, then update the contents accordingly.
Titles and headings¶
Title case for titles is recommended. Sentence case for headings is recommended. Title case for labels in reStructuredText files is recommended.
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.
Never use “here” as link text. Instead, make the relevant noun or phrase the link.