Skip to main content
Ctrl+K
Logo image Logo image

Documenteer

Site Navigation

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

Site Navigation

  • Rubin user guides
  • Technical notes
  • 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
  • Embedding a Redoc subsite for OpenAPI (HTTP API) documentation
  • Using the rst epilog for common links and substitutions
  • Redirecting pages when reorganizing content
  • Extending conf.py directly

Design features

  • Diagrams as code
  • Badges
  • Tab sets
  • Embedded videos

Markdown & Jupyter Notebooks

  • Using Markdown syntax in Rubin Observatory documentation
  • Including Jupyter notebooks in documentation

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

Embedding a Redoc subsite for OpenAPI (HTTP API) documentation

next

Redirecting pages when reorganizing content

Edit this page

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

Built with the PyData Sphinx Theme 0.12.0.

Created using Sphinx 8.1.3.