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.
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.
This PR adds initial support for using
documenteer.toml
configuration files, intended to be located beside a Sphinxconf.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
: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: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.