lsst-sqre / documenteer

Sphinx extensions, configurations, and tooling for Rubin Observatory documentation projects
https://documenteer.lsst.io
MIT License
5 stars 3 forks source link

DM-36085: Implement a documenteer.toml file for customizing Sphinx user guide configurations #130

Closed jonathansick closed 1 year ago

jonathansick commented 2 years ago

This PR adds initial support for using documenteer.toml configuration files, intended to be located beside a Sphinx conf.py file for configuring aspects of Documenteer Sphinx configuration presets.

The problem we're intenting to solve is the current recommendation for using the user guide configuration preset, documenteer.conf.guide:

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

Most configurations come from the from documenteer.conf.guide import * line, however, aspects that actually depend on the project itself need to be set afterwards. In most cases, this is benign, however in some cases like setting the GitHub repository URL for the icon link, this can lead to unnecessary complexity and fragility.

Through this PR, the documenteer configuration presets will pre-load a documenteer.toml file and use that in the configuration module itself (documenteer.conf.guide) to preset Sphinx configurations that depend on the project itself.

A simple documenteer.toml file looks like:

[project]
name = "Documenteer"
copyright = "2015 – 2022 AURA"
canonical_url = "https://documenteer.lsst.io"

[project.python]
package = "documenteer"

The intent is that users can either manually set metadata, or if they choose to add a Python package name, Documenteer will use Python's importlib.metadata and other tools for automatically discovering the project version, GitHub URL, etc.