This is an open source project and LSST welcomes contributions from the community. Feel free to create a GitHub issue to report a problem or even submit a pull request. Issues and pull requests are triaged into LSST's ticketing system, and we'll be able to resolve those issues or merge those pull requests for you.
If you're a member of the LSST Project, and have push access to this repository, please follow LSST DM's Development Workflow, particularly including the branching conventions.
Most of this project's content is written in reStructuredText. Please see the DM ReStructuredText Style Guide for information on how to format things like headers, lists, tables, images, and code samples.
Please write one sentence per line (as opposed to hard-wrapping text to a specific line width). This makes Git diffs and pull requests easier to use.
Use sentence case for headlines.
The Stack section of the DM Developer Guide has more information on how to create content for pipelines.lsst.io.
pipelines.lsst.io is automatically built and deployed with each lsst_distrib release.
As a contributor, you don't need to worry about updating the published site after you've merged updates to the documentation.
If you're writing new content, it's useful to be able to preview your changes. Depending on whether you're building pipelines.lsst.io as a whole, or just a single package, you can follow one of these tutorials to build and test your documentation changes:
- Building single-package documentation locally.
- Building the pipelines.lsst.io site locally.
- Building pipelines.lsst.io with Jenkins.
Tip: The Jenkins-based method enables you to publish a preview of the pipelines.lsst.io site based on your ticket branch, which is useful for code reviews. This method only works for branches on the lsst/pipelines_lsst_io repository itself, though.
Reference documentation for the build commands:
- stack-docs: used to build https://pipelines.lsst.io from the lsst/pipelines_lsst_io repository itself.
- package-docs: used to build documentation for single packages from their
doc/directories.
Background: Documenteer is the build tool for LSST's Sphinx-based documentation (like this project). To get a sense of how all this all works, you can read the Overview of the Stack documentation system.
Whether you have general questions about contributing to pipelines.lsst.io, or need help with a specific piece of documentation that you're contributing, you can get help a couple different ways:
- Ask a question in #dm-docs on Slack.
- Ask a question in the Data Management category on the LSST Community forum.