configure_technote

documenteer.sphinxconfig.technoteconf.configure_technote(meta_stream)

Builds a dict of Sphinx configuration variables given a central configuration for LSST Design Documents and a metadata YAML file.

This function refactors the common Sphinx conf.py script so that basic configurations are managed centrally in this module, while author-updatable metadata is stored in a metadata.yaml file in the document’s repository. To use this function, a conf.py need only look like

import os
from documenteer.sphinxconfig.technoteconf import configure_technote

metadata_path = os.path.join(os.path.dirname(__file__), 'metadata.yaml')
with open(metadata_path, 'r') as f:
    confs = configure_technote(f)
g = global()
g.update(confs)

And metadata.yaml looks like:

doc_id: 'LDM-152'
doc_title: 'Data Management Middleware Design'
copyright: '2015, AURA/LSST'
authors:
    - 'Kian-Tat Lim'
    - 'Ray Plante'
    - 'Gregory Dubois-Felsmann'
# Current document version
last_revised: 'October 10, 2013'
version: '10.0'
# dev_version_suffix: None  # e.g. 'alpha'/'beta'/'rc' if necessary

Parameters:

meta_stream (io.StringIO) – A file stream (e.g., from open()) for the metadata.yaml document in a design document’s repository.

Returns:

confs – Dictionary of configurations that should be added to the conf.py global namespace.

Return type:

dict