TSTN-005: TSSW Documentation Guide

  • Andrew Heyer

Latest Revision: 2019-10-28


This technote is not yet published.

This document guides a member of the TSSW Team to the correct location for their documentation.

1   Create Your Own Technote

Creating your own technote just like this one is simple. Here we will explore how to create one.

  1. Become a member of the tstn organization. Ask any current members to add you.

  2. Create your repository. Go to Slack and message create project to sqrbot-jr. You will then answer a series of questions.


    The name of the tech note


    A paragraph or less summary about the document


    The technote series(team based), choose tstn(Telescope and Site Tech Note)

    Initial Copyright Holder

    The copyright holder for the document. Choose AURA( Association of Universities for Reseach in Astronomy)


Before continuing with the steps check out the github repo you just created. It has a readme with lots of useful information such as a link to where your website is hosted.

  1. Perfect, your boilerplate repo is created. Now pull down the repo on your local machine. If you are struggling to find the URL to pull you can find the series number at the end of sqrbot-jr’s successful creation of the repo.
git clone https://github.com/lsst-tstn/tstn-{series_number}.git
  1. Install miniconda on your local machine so we can create a python environment that is able to build your website. Otherwise you will need to push and commit every single change to see changes to the site and that’s silly. Here’s the site link https://docs.conda.io/en/latest/miniconda.html.
  2. Create and activate a miniconda environment for your documentation work. Python 3.6 should work fine.
conda create --name documentation_env python=3.6
source activate documentation_env
  1. Now inside your miniconda environment install the python packages you need to build the static website. If you open the requirements.txt you will find that the only item there is Documenteer which is a DM provided package for generating websites. It comes with a nice theme and other boilerplating for the website.
pip install -r requirements.txt
  1. pip install any extensions you want to use. Before creating this documentation I knew I wanted to create some UML diagrams and plant UML was something I wanted to try out. You may also find out some extensions such as prompt are already installed via Documanteer.
pip install sphinxcontrib-plantuml
pip install sphinx-prompt
  1. The packages are installed in our python environment. We now need to just tell our project that we want to use it. Inside of the conf.py add the following line at the end. This is sphinx style syntax where if you want to include libraries you need to add it to your extensions variable. Also Make sure you add any sphinx extensions to the requirements.txt file for future developers and Travis CI as builds can break.
extensions = ['sphinxcontrib.plantuml', 'sphinx-prompt']
  1. Cool, you have documanteer and maybe some other python packages neatly tucked inside a python environment. You should be able to build your static website now.
make html
  1. If all went well you can now open the generated _build/html/index.html file. When you are happy with your local site push your changes. You can view the link to your site on the github repo.

2   configure your repo for docstrings