Ctrl+K
Logo image Logo image

Documenteer

Site Navigation

  • Rubin user guides
  • Technical notes
  • Science Pipelines
  • Sphinx extensions
  • Change Log
  • Development
  • Rubin docs

Site Navigation

  • Rubin user guides
  • Technical notes
  • Science Pipelines
  • Sphinx extensions
  • Change Log
  • Development
  • Rubin docs

Section Navigation

  • Rubin user guide features

First steps

  • Setting up the Documenteer configuration for Rubin user guides
  • Organizing content in a Rubin user guide

Advanced configuration

  • Configuring Python projects in documenteer.toml
  • Using the rst epilog for common links and substitutions
  • Extending conf.py directly

Design features

  • Diagrams as code
  • Badges
  • Tab sets

Reference

  • documenteer.toml reference
  • The documenteer.conf.guide configuration preset

Using the rst epilog for common links and substitutions#

Sphinx provides a feature for dynamically including content at the bottom of every reStructuredText page, called the rst_epilog in the standard Sphinx configuration. This epilog is a great place to put standard Sphinx substitutions and link targets so that they can be reused throughout a documentation project.

In the Rubin user guide configuration, you can configure a standard reStructuredText file to serve as the content for rst_epilog with the sphinx.rst_epilog_file configuration:

documenteer.toml#
 [sphinx]
 rst_epilog_file = "_rst_epilog.rst"

Then in the referenced _rst_epilog.rst file, include links and substitutions:

_rst_epilog.rst#
.. _Astropy Project: https://www.astropy.org

.. |required| replace:: :bdg-primary-line:`Required`
.. |optional| replace:: :bdg-secondary-line:`Optional`

Now on any page, you can use those links and substitutions:

|required|

`Astropy Project`_

previous

Configuring Python projects in documenteer.toml

next

Extending conf.py directly

Edit this page

© Copyright 2015-2022 Association of Universities for Research in Astronomy, Inc. (AURA).

Created using Sphinx 5.3.0.