DM-9734: lsstsw documentation site (work in progress)

.travis.yml

@@ -6,6 +6,16 @@ matrix:
       language: python
       python: "3.4"
       env: MODE=lint
+    - os: linux
+      language: python
+      python: "3.4"
+      env:
+        - MODE=docs
+        - LTD_MASON_PRODUCT="lsstsw"
+        - LTD_MASON_BUILD=true
+        # LTD Mason/LSST the Docs credentials
+        - secure: "dDFZK2drIdRWntjtlRjGOZevEJ4YBXd8oFi8k1J8F4hYfjX7vOWHr+t76+TSjZIjYs2nyoYFZSK6Du5ZrqRJYxntS4DwcU8Woj5iJ7rbPt6xSUQexhAahKefoarbvYEkQt/USZnDzcLPXvvh7yT9FiMx28/3f+C6iNFR6w4FpvA="
+        - secure: "jzUFcgO7x+Fgp5ZYFmxxWMTPg0GkpgwfbJcyEgR5CiDGJQQh43NVuAJf5AdpzIdQk1wGOwrEfPx+wEPdAHAhqWlRWtfnkXEcO4dPzeGD3WmNHb6B4BDyAyrNnG+RINYq2FsnY9ymps/DMbFGcC8Efua7YO9cYruJE29NUachzVk="
     - os: linux
       env:
         - MODE=versiondb
@@ -61,6 +71,12 @@ script: |
       pip install -r requirements.txt
       ./bin/repos-lint ./etc/repos.yaml
       ;;
+    docs)
+      pip install -r requirements.txt
+      pip install -r docs/requirements.txt
+      sphinx-build -b html -a -W -d docs/_build/doctree docs docs/_build/html
+      ltd-mason-travis --html-dir docs/_build/html --verbose
+      ;;
     deploy*)
       CONDA_PREFIX="2"
       if [[ $MODE == deploy-bleed ]]; then

docs/.gitignore

@@ -0,0 +1 @@
+_build

docs/Makefile

@@ -0,0 +1,60 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+	@echo "  dummy      to check syntax errors of document sources"
+
+.PHONY: clean
+clean:
+	rm -rf $(BUILDDIR)/*
+	rm -rf py-api
+
+.PHONY: html
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: linkcheck
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+.PHONY: doctest
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY: coverage
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/coverage/python.txt."
+
+.PHONY: dummy
+dummy:
+	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
+	@echo
+	@echo "Build finished. Dummy builder generates no files."

docs/README.md

@@ -0,0 +1,18 @@
+# lsstsw documentation
+
+This directory contains lsstsw's documentation source.
+**You can find this documentation on the web at https://lsstsw.lsst.io.**
+
+## Contributing workflow
+
+1. Clone `https://github.com/lsst/lsstsw`.
+2. Edit and commit documentation to reStructuredText files here using the [DM ticket branch workflow](https://developer.lsst.io/processes/workflow.html#ticket-branches).
+3. Push the branch and find the edition at https://lsstsw.lsst.io/v.
+4. Pull request the documentation change.
+   Once it's approved and merged to master the main documentation at https://lsstsw.lsst.io will be updated.
+
+## Building docs locally
+
+1. Install requirements: ``pip install -r requirements.txt``.
+2. Make the docs: ``make html``.
+3. View the docs at: ``_build/html/index.html``.

docs/_static/README.md

@@ -0,0 +1,3 @@
+# _static/
+
+Place static assets (images, and so forth)

docs/conf.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python
+"""Sphinx configurations to build product documentation.
+"""
+
+from documenteer.sphinxconfig.stackconf import build_package_configs
+from documenteer.sphinxconfig.utils import read_git_branch
+
+
+_g = globals()
+_g.update(build_package_configs(
+    project_name='lsstsw',
+    copyright='2017 Association of Universities for '
+              'Research in Astronomy, Inc.',
+    version=read_git_branch(),
+    doxygen_xml_dirname=None))
+
+intersphinx_mapping = {
+    'python': ('http://docs.python.org/3/', None)
+}

docs/index.rst

@@ -0,0 +1,46 @@
+######
+lsstsw
+######
+
+``lsstsw`` is a build tool for the LSST software stack.
+
+``lsstsw`` is on GitHub at https://github.com/lsst/lsstsw/.
+
+Quick start
+===========
+
+Clone ``lsstsw``:
+
+.. code-block:: bash
+
+   git clone https://github.com/lsst/lsstsw
+   cd lsstsw
+
+Deploy and build the LSST software stack:
+
+.. code-block:: bash
+
+   ./bin/deploy
+   . bin/setup.sh
+   rebuild lsst_distrib
+
+Tag the build as current (get ``bNNNN`` from the previous console output):
+
+.. code-block:: bash
+
+   eups tags --clone bNNNN current
+
+Set up the stack:
+
+.. code-block:: bash
+
+   eups setup lsst_distrib
+
+Command reference
+=================
+
+.. toctree::
+
+   scripts/deploy
+   scripts/setup
+   scripts/rebuild

docs/requirements.txt

@@ -0,0 +1,5 @@
+Sphinx>=1.5.3
+astropy-helpers>=1.2
+documenteer>=0.1.11
+lsst-sphinx-bootstrap-theme
+ltd-mason==0.2.2

docs/scripts/deploy.rst

@@ -0,0 +1,46 @@
+.. _scripts-deploy:
+
+##############
+deploy command
+##############
+
+Synopsis
+========
+
+**deploy** [-3] [-b] [-h]
+
+Description
+===========
+
+:program:`deploy` installs ``lsstsw``, setting up: EUPS, miniconda Python (2.7 *or* 3.5), and Git LFS.
+:program:`deploy` should only be run once.
+
+Example: default lsstsw set up
+------------------------------
+
+.. code-block:: bash
+
+   git clone https://github.com/lsst/lsstsw
+   cd lsstsw
+   ./bin/deploy
+
+Example: Python 3 lsstsw set up
+-------------------------------
+
+.. code-block:: bash
+
+   git clone https://github.com/lsst/lsstsw
+   cd lsstsw
+   ./bin/deploy -3
+
+Options
+=======
+
+-3
+   Use Python 3, via miniconda. Otherwise, the default is Python 2.7.
+
+-b
+   Use bleeding edge Conda packages.
+
+-h
+   Show a help message.

docs/scripts/rebuild.rst

@@ -0,0 +1,67 @@
+.. _scripts-rebuild:
+
+###############
+rebuild command
+###############
+
+Synopsis
+========
+
+**rebuild** [-p] [-n] [-u] [-r <*ref*> [-r <*ref2*> [...]]] [-t <*eupstag*>] [*product1* [*product2* [...]]]
+
+Description
+===========
+
+:program:`rebuild` clones and builds EUPS products, including their dependencies.
+
+To build a single product from ``master``:
+
+.. code-block:: bash
+
+   rebuild lsst_distrib
+
+To build multiple products:
+
+.. code-block:: bash
+
+   rebuild lsst_distrib qserv_distrib
+
+Building from branches
+----------------------
+
+:program:`lsstsw` enables you to clone and build development branches.
+
+To build ``lsst_distrb``, but using the Git branch ``my-feature`` when it's available in a package:
+
+.. code-block:: bash
+
+   rebuild -r my-feature lsst_distrib
+
+Multiple ticket branches across multiple products can be built in order of priority:
+
+.. code-block:: bash
+
+   rebuild -r feature-1 -r feature-2 lsst_distrib
+
+In this example, a ``feature-1`` branch will be used in any product's Git repository.
+A ``feature-2`` branch will be used secondarily in repositories where ``feature-1`` doesn't exist.
+Finally, ``lsstsw`` falls back to using the ``master`` branch for repositories that lack both ``feature-1`` and ``feature-2``.
+
+Options
+=======
+
+-p
+   Prep only.
+
+-n
+   No fetch.
+
+-u
+   Update.
+
+-r <git ref>
+   Rebuild using the Git ref.
+   Multiple ``-r`` arguments can be given, in order or priority.
+
+-t
+   Tag.

docs/scripts/setup.rst

@@ -0,0 +1,20 @@
+.. _scripts-setup:
+
+################
+setup.sh command
+################
+
+The :program:`setup.sh` command initializes an ``lsstsw`` installation in your :program:`bash` or :program:`zsh` shell.
+For :program:`tcsh` shell users, a :program:`setup.csh` equivalent is available.
+
+:program:`setup.sh` is intended to be sourced by every new shell that uses ``lsstsw``.
+
+Basic usage is:
+
+.. code-block:: bash
+
+   source $lsstsw/bin/setup.sh
+
+where ``$lsstsw`` is the path to the ``lsstsw`` directory.
+
+You may ``setup.sh`` from your :file:`~/.bashrc` or :file:`~/.zshrc` login files.