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 main branch are automatically deployed to https://developer.lsst.io. Other branches are also deployed: find them at https://developer.lsst.io/v.

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.

5. If your build on GitHub Actions is successful, your branch will be published with LSST the Docs. Find your branch listed at https://developer.lsst.io/v.

6. Once you're done, press the green button on your pull request to merge to main. Your changes are 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 main.

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 by finding it at https://developer.lsst.io/v (see Step #5 of § Contributing, above).

License

Copyright 2015-2019 Association of Universities for Research in Astronomy, Inc. (AURA).

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.