Documentation builders

This module is the starting point for building documentation, and is responsible to figure out what to build and with which options. The actual documentation build for each individual document is then done in a subprocess call to Sphinx, see builder_helper(). Note that

• The builders are configured with build_options.py;

• The Sphinx subprocesses are configured in conf.py.

DocBuilder is the base class of all Builders. It has builder helpers html(), latex(), pdf(), inventory(), etc, which are invoked depending on the output type. Each type corresponds with the Sphinx builder format, except that pdf is Sphinx latex builder plus compiling latex to pdf. Note that Sphinx inventory builder is not native to Sphinx but provided by Sage. See sage_docbuild/ext/inventory_builder.py. The Sphinx inventory builder is a dummy builder with no actual output but produces doctree files in local/share/doctree and inventory.inv inventory files in local/share/inventory.

The reference manual is built in two passes, first by ReferenceBuilder with inventory output type and secondly with``html`` output type. The ReferenceBuilder itself uses ReferenceTopBuilder and ReferenceSubBuilder to build subcomponents of the reference manual. The ReferenceSubBuilder examines the modules included in the subcomponent by comparing the modification times of the module files with the times saved in local/share/doctree/reference.pickle from the previous build. Then new rst files are generated for new and updated modules. See get_new_and_updated_modules().

After Issue #31948, when Sage is built, ReferenceBuilder is not used and its responsibility is now taken by the Makefile in $SAGE_ROOT/src/doc.

class sage_docbuild.builders.AllBuilder

Bases: object

A class used to build all of the documentation.

get_all_documents()

Return a list of all of the documents.

A document is a directory within one of the language subdirectories of SAGE_DOC_SRC specified by the global LANGUAGES variable.

EXAMPLES:

Sage

sage: from sage_docbuild.builders import AllBuilder
sage: documents = AllBuilder().get_all_documents()
sage: 'en/tutorial' in documents  # optional - sage_spkg
True
sage: documents[0] == 'en/reference'
True

Python

>>> from sage.all import *
>>> from sage_docbuild.builders import AllBuilder
>>> documents = AllBuilder().get_all_documents()
>>> 'en/tutorial' in documents  # optional - sage_spkg
True
>>> documents[Integer(0)] == 'en/reference'
True

class sage_docbuild.builders.DocBuilder(name, lang='en')

Bases: object

INPUT:

• name – the name of a subdirectory in SAGE_DOC_SRC, such as ‘tutorial’ or ‘bordeaux_2008’

• lang – (default “en”) the language of the document.

changes(*args, **kwds)

clean(*args)

html(*args, **kwds)

htmlhelp(*args, **kwds)

inventory(*args, **kwds)

json(*args, **kwds)

latex(*args, **kwds)

linkcheck(*args, **kwds)

pdf()

Build the PDF files for this document.

This is done by first (re)-building the LaTeX output, going into that LaTeX directory, and running ‘make all-pdf’ there.

EXAMPLES:

Sage

sage: from sage_docbuild.builders import DocBuilder
sage: b = DocBuilder('tutorial')
sage: b.pdf() #not tested

Python

>>> from sage.all import *
>>> from sage_docbuild.builders import DocBuilder
>>> b = DocBuilder('tutorial')
>>> b.pdf() #not tested

pickle(*args, **kwds)

web(*args, **kwds)

class sage_docbuild.builders.ReferenceBuilder(name, lang='en')

Bases: AllBuilder

This class builds the reference manual. It uses DocBuilder to build the top-level page and ReferenceSubBuilder for each sub-component.

get_all_documents(refdir)

Return a list of all reference manual components to build.

We add a component name if it’s a subdirectory of the manual’s directory and contains a file named ‘index.rst’.

We return the largest component (most subdirectory entries) first since they will take the longest to build.

EXAMPLES:

Sage

sage: from sage_docbuild.builders import ReferenceBuilder
sage: b = ReferenceBuilder('reference')
sage: refdir = os.path.join(os.environ['SAGE_DOC_SRC'], 'en', b.name)  # optional - sage_spkg
sage: sorted(b.get_all_documents(refdir))  # optional - sage_spkg
['reference/algebras',
 'reference/arithgroup',
 ...,
 'reference/valuations']

Python

>>> from sage.all import *
>>> from sage_docbuild.builders import ReferenceBuilder
>>> b = ReferenceBuilder('reference')
>>> refdir = os.path.join(os.environ['SAGE_DOC_SRC'], 'en', b.name)  # optional - sage_spkg
>>> sorted(b.get_all_documents(refdir))  # optional - sage_spkg
['reference/algebras',
 'reference/arithgroup',
 ...,
 'reference/valuations']

class sage_docbuild.builders.ReferenceSubBuilder(*args, **kwds)

Bases: DocBuilder

This class builds sub-components of the reference manual. It is responsible for making sure that the auto generated reST files for the Sage library are up to date.

When building any output, we must first go through and check to see if we need to update any of the autogenerated reST files. There are two cases where this would happen:

1. A new module gets added to one of the toctrees.

2. The actual module gets updated and possibly contains a new title.

auto_rest_filename(module_name)

Return the name of the file associated to a given module

EXAMPLES:

Sage

sage: from sage_docbuild.builders import ReferenceSubBuilder
sage: ReferenceSubBuilder("reference").auto_rest_filename("sage.combinat.partition")
'.../en/reference/sage/combinat/partition.rst'

Python

>>> from sage.all import *
>>> from sage_docbuild.builders import ReferenceSubBuilder
>>> ReferenceSubBuilder("reference").auto_rest_filename("sage.combinat.partition")
'.../en/reference/sage/combinat/partition.rst'

cache_filename()

Return the filename where the pickle of the reference cache is stored.

clean_auto()

Remove all autogenerated reST files.

get_all_included_modules()

Return an iterator for all modules which are included in the reference manual.

get_all_rst_files(exclude_sage=True)

Return an iterator for all rst files which are not autogenerated.

get_cache()

Retrieve the reference cache which contains the options previously used by the reference builder.

If it doesn’t exist, then we just return an empty dictionary. If it is corrupted, return an empty dictionary.

get_modified_modules()

Return an iterator for all the modules that have been modified since the documentation was last built.

get_module_docstring_title(module_name)

Return the title of the module from its docstring.

get_modules(filename)

Given a filename for a reST file, return an iterator for all of the autogenerated reST files that it includes.

get_new_and_updated_modules()

Return an iterator for all new and updated modules that appear in the toctrees, and remove obsolete old modules.

get_sphinx_environment()

Return the Sphinx environment for this project.

get_unincluded_modules()

Return an iterator for all the modules in the Sage library which are not included in the reference manual.

print_included_modules()

Print all of the modules that are included in the Sage reference manual.

print_modified_modules()

Print a list of all the modules that have been modified since the documentation was last built.

print_new_and_updated_modules()

Print all the modules that appear in the toctrees that are newly included or updated.

print_unincluded_modules()

Print all of the modules which are not included in the Sage reference manual.

save_cache()

Pickle the current reference cache for later retrieval.

update_mtimes()

Update the modification times for reST files in the Sphinx environment for this project.

write_auto_rest_file(module_name)

Write the autogenerated reST file for module_name.

class sage_docbuild.builders.ReferenceTopBuilder(*args, **kwds)

Bases: DocBuilder

This class builds the top-level page of the reference manual.

html()

Build the top-level document.

class sage_docbuild.builders.SingleFileBuilder(path)

Bases: DocBuilder

This is the class used to build the documentation for a single user-specified file. If the file is called ‘foo.py’, then the documentation is built in DIR/foo/ if the user passes the command line option “-o DIR”, or in DOT_SAGE/docbuild/foo/ otherwise.

class sage_docbuild.builders.WebsiteBuilder(name, lang='en')

Bases: DocBuilder

clean()

When we clean the output for the website index, we need to remove all of the HTML that were placed in the parent directory.

In addition, remove the index file installed into the root doc directory.

html()

After we have finished building the website index page, we copy everything one directory up, that is, to the base diectory html/en.

In addition, an index file is installed into the root doc directory.

Thus we have three index.html files:

html/en/website/index.html (not used) html/en/index.html (base directory) index.html (root doc directory)

pdf()

Build the website hosting pdf docs.

sage_docbuild.builders.build_many(target, args, processes=None)

Thin wrapper around \(sage_docbuild.utils.build_many\) which uses the docbuild settings NUM_THREADS and ABORT_ON_ERROR.

sage_docbuild.builders.build_other_doc(args)

sage_docbuild.builders.build_ref_doc(args)

sage_docbuild.builders.builder_helper(type)

Return a function which builds the documentation for output type type.

sage_docbuild.builders.get_builder(name)

Return an appropriate Builder object for the document name.

DocBuilder and its subclasses do all the real work in building the documentation.

sage_docbuild.builders.get_documents()

Return a list of document names the Sage documentation builder will accept as command-line arguments.