LSST DM Developer Guide

This repository contains the content for the LSST DM Developer Guide, https://developer.lsst.io.

Everyone in LSST DM is encouraged to not only use this guide, but also contribute to it. The contribution process is outlined below.

Documentation is written in reStructuredText, built using Sphinx, and hosted with our in-house platform, LSST the Docs.

Changes to the master branch are automatically deployed to https://developer.lsst.io. Branches are also deployed, see below for a guide to branch URLs.

Contributing

1. Clone this repository: git clone https://github.com/lsst-dm/dm_dev_guide && cd dm_dev_guide.

2. Create a branch. This can either be an informal user branch or a full-fledged ticket branch tracked in JIRA. See the DM Workflow guide for details.

3. Make and commit your edits. Content is written in reStructuredText. Our reStructuredText Style Guide covers the syntax you'll need.

4. Push your development branch to GitHub and make a pull request. The pull request page will help you track the publishing and testing status of your branch. You can also track your branch's status directly on Travis CI.

5. If your build on Travis is successful, your branch will be published with LSST the Docs.

   • If you have a ticket branch (tickets/DM-NNNN) the published URL is https://developer.lsst.io/v/DM-NNNN.
   • If you have a user branch (u/username/name) replace all / characters in your branch's name with - characters, e.g.: https://developer.lsst.io/v/u-username-name.

   Sorry this is complicated! We're working on a version dashboard view.

6. Once you're done, press the green button on your pull request to merge to master. Your changes will be automatically published to the main URL: https://developer.lsst.io. Don't worry about messing things up, GitHub branch protections will ensure that your edits build successfully, and that your branch is up-to-date with master.

Installing and building these docs locally

Although LSST the Docs will publish your development branch, you might want to build this documentation locally.

Assuming you've cloned the docs (following the guide above):

1. Create a Python virtual environment for this project using your tool of choice: virtualenvwrapper or pyvenv (for Python 3).

2. Install dependencies

   pip install -r requirements.txt
   

3. Compile the HTML by running

   make html
   

The built site is in the _build/html directory.

Editing entirely on GitHub

If you're in a hurry, you don't need to worry about cloning the Developer Guide; you can do everything on GitHub.com. See GitHub's documentation on editing files and creating branches entirely from GitHub.com.

Remember to preview your published branch (see Step #5 of § Contributing, above).

License

Copyright 2015-2018 Association of Universities for Research in Astronomy.

LSST DM Developer Guide by Association of Universities for Research in Astronomy, Inc. is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at https://github.com/lsst_dm/dm_dev_guide.