User guides

User guides help users and team members understand and use your projects with conceptual documentation, how-to procedures, tutorials, and reference documentation. At Rubin Observatory, every software package, web service, and even data release has a corresponding user guide. Documenteer provides a configuration profile for creating branded user guides with Sphinx.

• Rubin user guide features
  • Based on the PyData Sphinx Theme
  • Configuration with documenteer.toml
  • Markdown support
  • Diagrams as code
  • Python APIs with automodapi and autodoc

First steps

• Setting up the Documenteer configuration for Rubin user guides
  • Python dependency
  • Create a basic conf.py Sphinx configuration file
  • Create a basic documenteer.toml configuration file
  • Next steps
• Organizing content in a Rubin user guide
  • Navigational levels in the HTML theme
  • Creating sections
  • Creating section navigation and segments
  • Suggested layouts

Advanced configuration

• Configuring Python projects in documenteer.toml
  • Walkthrough
  • Overriding Python packaging metadata
  • Using alternative labels in pyproject.toml’s [project.urls]
• Embedding a Redoc subsite for OpenAPI (HTTP API) documentation
  • 1. Create a function to generate the OpenAPI docs
  • 2. Add a stub page for the Redoc subsite
  • 3. Configuration in documenteer.toml
  • Additional resources
• Using the rst epilog for common links and substitutions
• Redirecting pages when reorganizing content
  • Adding a page redirect in documenteer.toml
  • Redirects for deleted pages
• Extending conf.py directly
  • Using the [sphinx] table in documenteer.toml
  • Editing conf.py

Design features

• Diagrams as code
  • Basic syntax
  • Mermaid diagram types
  • Diagrams for architectural diagrams
• Badges
  • Badge styles
  • Reusable badges
  • Link and reference badges
• Tab sets
  • Create a tab set
  • Synchronized tab sets
  • Automatic tab items for code samples
• Embedded videos
  • Embedding a Vimeo video
  • Embedding a YouTube video
  • More information

Markdown & Jupyter Notebooks

• Using Markdown syntax in Rubin Observatory documentation
  • Mixing Markdown and reStructuredText
  • Roles
  • Directives
  • More resources
• Including Jupyter notebooks in documentation
  • Using ipynb files as content pages
  • Computation
  • Examples
  • Further reading

Science Pipelines

• Pipelines
  • Installing Documenteer for pipelines.lsst.io
  • Overview of the pipelines.lsst.io build system
  • stack-docs command-line app
  • package-docs command-line app
  • Sphinx configuration for stacks and packages
  • Cross-linking the Doxygen-built C++ API reference with the lsstcc role

Reference

• documenteer.toml reference
  • [project] table
  • [project.openapi]
  • [project.openapi.generator]
  • [project.python]
  • [sphinx]
  • [sphinx.redirects]
  • [sphinx.theme]
  • [sphinx.intersphinx]
  • [sphinx.intersphinx.projects]
  • [sphinx.linkcheck]
• The documenteer.conf.guide configuration preset