Documentation Guide

This topic outlines writing and creating TSSW documentation.

RST Guide

Use DM’s Restructured Text Style Guide for reference.

Doc Folder Template

cookiecutter_tssw_csc_doc is a template meant to help start working on documentation for CSCs. The following steps will explain how to use it.

pip install cookiecutter # Install cookiecutter in the virtual environment of the development docker image
cd {csc_root_folder} # change directory into your csc folder
cookiecutter https://github.com/lsst-ts/cookiecutter_tssw_csc_doc
doc [doc]: # The name of the folder where the documentation goes, this option should only be changed if the standard folder name is changed.
csc_name [Barracuda]: # the name of the CSC, affects things like api generation, xml badge location
csc_repo_name [ts_barracuda]: # The name of the repo should include ``ts_`` or ``dm_``, affects things like the badges for JIRA, GitHub and Jenkins

Once those three questions are answered then a brand new doc folder will be added to the CSC. Inside of the files, there are comments that explain how to fill out each section in detail.

Conf.py

The conf.py file is a Sphinx configuration file that contains information on Sphinx should build the site as well as any extensions that should be loaded. You can find the template conf.py at lsst-ts/cookiecutter_tssw_csc_doc. Documenteer is a tool that provides pre-made Sphinx configurations for 3 different purposes that SQRE provides the project.

  1. pipelines

  2. guide

  3. technote

It also provides several project extensions for the RSP packages. All documentation is available at https://documenteer.lsst.io.

The template does not yet provide compatibility with documenteer 1.0 and above. See the Documenteer Configuration section for how to accomplish this.

Publishing lsst.io Site

This functionality is included in the DevelopPipeline for the Jenkins Shared Library.

Documenteer Configuration

With documenteer 1.0 and above, it is now necessary to add a documenteer.toml file.

Create a documenteer.toml file using https://documenteer.lsst.io/guides/toml-reference.html as reference material. A basic documenteer.toml example is provided below.

# This template contains enough information for documenteer to build

[project]
# The title of the index page.
title = "" # i.e. CBP
# Copyright information displayed on the footer of each page
copyright = "2019-2024 Association of Universities for Research in Astronomy, Inc. (AURA)"

[project.python]
# pyproject.toml package name, fills out unseen metadata
package = "" # i.e. ts_cbp (should match the name that importlib.metadata uses/pyproject.toml name)
documentation_url_key = "documentation"
github_url_key = "source_code"

[sphinx]
extensions = ["sphinx-jsonschema"]

[sphinx.intersphinx.projects]
ts-xml = "https://ts-xml.lsst.io"
salobj = "https://ts-salobj.lsst.io"
python = "https://docs.python.org/3.13/"

Note

You need to have the package available via pip in order to make the api generation code work. This is true for all of the packages that your package depends on. Conda packages also satisfy the requirement.

You also need to change first line in conf.py to import from the guide config with

from documenteer.conf.guide import *

This uses a new theme which provides new features such as tabbed groups and mermaid diagram support.

To build it locally

sphinx-build -b html doc doc/_build/html