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]
• Using the rst epilog for common links and substitutions
• 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

Reference

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