In DM-35969 I added initial support for the pydata-sphinx-theme in Documenteer for Rubin user guides. Right now the how-to guide for integrating with this theme boils down to this example Sphinx conf.py file:

from documenteer.conf.guide import *

# General information about the project.

project = "Example"

copyright = (

    "2015-2022 "

    "Association of Universities for Research in Astronomy, Inc. (AURA)"

)

# The version info for the project you're documenting, acts as replacement for

# |version| and |release|, also used in various other places throughout the

# built documents.

version = "1.0.0"

release = version

# HTML theme option overrides

html_theme_options["icon_links"][0]["url"] = "https://github.com/lsst/example"

html_theme_options["logo"]["text"] = project

# The name for this set of Sphinx documents.  If None, it defaults to

# "<project> v<release> documentation".

html_title = project

# A shorter title for the navigation bar.  Default is the same as html_title.

html_short_title = project

Notice how several metadata details need to be manually set, such as the project name, and the GitHub URL. In particular, the configuration for the GitHub URL is tricky because it's part of an existing data structure related to the icon bar, and if the icon bar is re-ordered in the configuration pre-set, this scheme on the user's conf.py will fail.

A better approach is to have a static configuration sidecar file that a user can put in their documentation project. Documenteer's configuration preset can find this file and parse it will setting up the Sphinx configurations.

Previously we've done this with YAML files for technotes. This time around, let's look at TOML files since they're becoming the configuration format of choice in the Python community. For example:

[project]

name = "Documenteer"

copyright = "2015 – 2022 AURA"

canonical_url = "https://documenteer.lsst.io"

[project.python]

package = "documenteer"

Potentially we can do auto-discovery depending on what configuration is given. For example, if package is set, we can use importlib to infer the version information. And also to discover the GitHub repo URL using the project metadata in pyproject.toml (also available through importlib). But if the project isn't a Python package, we also support fields like version and github_url for explicitly setting that information. i.e. if those fields are set, documenteer won't attempt to infer that information from other sources.