Documentation builders

Note

If you are a developer and want to build the SageMath documentation from source, refer to developer’s guide.

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.DocBuilder(name: str, options: BuildOptions)

Bases: object

INPUT:

• name – the name of a subdirectory in doc/<lang>, such as ‘tutorial’ or ‘installation’

changes(*args, **kwds)

alias of f().

clean(*args)

html(*args, **kwds)

alias of f().

htmlhelp(*args, **kwds)

alias of f().

inventory(*args, **kwds)

alias of f().

json(*args, **kwds)

alias of f().

latex(*args, **kwds)

alias of f().

linkcheck(*args, **kwds)

alias of f().

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: from sage_docbuild.builders import DocBuilder
sage: from sage_docbuild.build_options import BuildOptions
sage: options = BuildOptions(source_dir = Path('src/doc'))
sage: builder = DocBuilder('tutorial', options)
sage: builder.pdf() #not tested

pickle(*args, **kwds)

alias of f().

web(*args, **kwds)

alias of f().

class sage_docbuild.builders.ReferenceBuilder(name: str, options: BuildOptions)

Bases: object

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

class sage_docbuild.builders.ReferenceSubBuilder(name: str, options: BuildOptions)

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: from sage_docbuild.builders import ReferenceSubBuilder
sage: from sage_docbuild.build_options import BuildOptions
sage: options = BuildOptions(source_dir = Path('src/doc'))
sage: ReferenceSubBuilder("reference", options).auto_rest_filename("sage.combinat.partition")
...Path('src/doc/en/reference/sage/combinat/partition.rst')

cache_file()

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()

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(file)

Given 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(name: str, options: BuildOptions)

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: str, options: BuildOptions)

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_ref_doc(args)

sage_docbuild.builders.builder_helper(type)

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

sage_docbuild.builders.get_all_documents(source)

Return a list of all of the documents, relative to the source directory.

A document is a directory within one of the language subdirectories of doc.

EXAMPLES:

sage: from sage_docbuild.builders import get_all_documents
sage: documents = get_all_documents(Path('src/doc'))
sage: Path('en/tutorial') in documents
True

sage_docbuild.builders.get_all_reference_documents(source)

Return a list of all reference manual documents to build, relative to the specified source directory.

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

The order corresponds to the order in which the documents should be built.

EXAMPLES:

sage: from sage_docbuild.builders import get_all_reference_documents
sage: documents = get_all_reference_documents(Path('src/doc/en'))
sage: Path('reference/algebras') in documents
True

sage_docbuild.builders.get_builder(name, options)

Return an appropriate Builder object for the document name.

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