Sphinx build configuration

This file contains configuration needed to customize Sphinx input and output behavior.

sage_docbuild.conf.add_page_context(app, pagename, templatename, context, doctree)

sage_docbuild.conf.linkcode_resolve(domain, info)

sage_docbuild.conf.reference_subdocument(directory=None)

Return the configuration values proper to one sub-document of the reference manual.

Every sub-document is a Sphinx project of its own, with a configuration file that takes the shared configuration from this module and then the values returned here, which only depend on where the sub-document lives:

from sage_docbuild.conf import *
from sage_docbuild.conf import reference_subdocument

globals().update(reference_subdocument())

Anything proper to a single sub-document belongs in its configuration file, after that call.

INPUT:

• directory – the directory of the sub-document; defaults to the current directory, which is the one holding the configuration file that Sphinx is reading

As a side effect, the shared html_theme_options and latex_elements are given the entries that depend on the sub-document; a Sphinx run builds a single document, so they cannot be shared.

EXAMPLES:

Sage

sage: import os, tempfile
sage: from sage_docbuild.conf import reference_subdocument
sage: def subdocument(name, index):
....:     directory = os.path.join(tempfile.mkdtemp(), name)
....:     os.mkdir(directory)
....:     with open(os.path.join(directory, 'index.rst'), 'w') as f:
....:         _ = f.write(index)
....:     return reference_subdocument(directory)

sage: config = subdocument('algebras', 'Algebras\n========\n')
sage: config['htmlhelp_basename']
'algebras'
sage: config['html_title']
'Algebras'
sage: config['latex_documents']
[('index', 'algebras.tex', 'Algebras', 'The Sage Development Team', 'manual')]
sage: config['multidocs_is_master']
False

Python

>>> from sage.all import *
>>> import os, tempfile
>>> from sage_docbuild.conf import reference_subdocument
>>> def subdocument(name, index):
...     directory = os.path.join(tempfile.mkdtemp(), name)
...     os.mkdir(directory)
...     with open(os.path.join(directory, 'index.rst'), 'w') as f:
...         _ = f.write(index)
...     return reference_subdocument(directory)

>>> config = subdocument('algebras', 'Algebras\n========\n')
>>> config['htmlhelp_basename']
'algebras'
>>> config['html_title']
'Algebras'
>>> config['latex_documents']
[('index', 'algebras.tex', 'Algebras', 'The Sage Development Team', 'manual')]
>>> config['multidocs_is_master']
False

Sage Live

import os, tempfile
from sage_docbuild.conf import reference_subdocument
def subdocument(name, index):
    directory = os.path.join(tempfile.mkdtemp(), name)
    os.mkdir(directory)
    with open(os.path.join(directory, 'index.rst'), 'w') as f:
        _ = f.write(index)
    return reference_subdocument(directory)
config = subdocument('algebras', 'Algebras\n========\n')
config['htmlhelp_basename']
config['html_title']
config['latex_documents']
config['multidocs_is_master']

A title in backticks is math, which the HTML title writes with dollars:

Sage

sage: subdocument('padics', '`p`-adics\n=========\n')['html_title']
'$p$-adics'

Python

>>> from sage.all import *
>>> subdocument('padics', '`p`-adics\n=========\n')['html_title']
'$p$-adics'

Sage Live

subdocument('padics', '`p`-adics\n=========\n')['html_title']

Without a title, the name of the directory is used:

Sage

sage: subdocument('padics', 'No title here.\n')['html_title']
'Padics'

Python

>>> from sage.all import *
>>> subdocument('padics', 'No title here.\n')['html_title']
'Padics'

Sage Live

subdocument('padics', 'No title here.\n')['html_title']

sage_docbuild.conf.setup(app)

Make live