Sage docbuild main#

This module defines the Sage documentation build command:

sage --docbuild [OPTIONS] DOCUMENT (FORMAT | COMMAND)

If FORMAT is given, it builds DOCUMENT in FORMAT. If COMMAND is given, it returns information about DOCUMENT.

Run sage --docbuild to get detailed explanations about arguments and options.

Positional arguments:

DOCUMENT                  name of the document to build. It can be either one
                          of the documents listed by -D or 'file=/path/to/FILE' to build documentation
                          for this specific file.
FORMAT or COMMAND         document output format (or command)

Standard options:

-h, --help                show a help message and exit
-H, --help-all            show an extended help message and exit
-D, --documents           list all available DOCUMENTs
-F, --formats             list all output FORMATs
-C DOC, --commands DOC    list all COMMANDs for DOCUMENT DOC; use 'all' to list all
-i, --inherited           include inherited members in reference manual; may be slow, may fail for PDF output
-u, --underscore          include variables prefixed with '_' in reference
                          manual; may be slow, may fail for PDF output
-j, --mathjax, --jsmath   ignored for backwards compatibility
--no-plot                 do not include graphics auto-generated using the '.. plot' markup
--include-tests-blocks    include TESTS blocks in the reference manual
--no-pdf-links            do not include PDF links in DOCUMENT 'website';
                          FORMATs: html, json, pickle, web
--warn-links              issue a warning whenever a link is not properly
                          resolved; equivalent to '--sphinx-opts -n' (sphinx option: nitpicky)
--check-nested            check picklability of nested classes in DOCUMENT 'reference'
--no-prune-empty-dirs     do not prune empty directories in the documentation sources
-N, --no-colors           do not color output; does not affect children
-q, --quiet               work quietly; same as --verbose=0
-v LEVEL, --verbose LEVEL report progress at LEVEL=0 (quiet), 1 (normal), 2
                          (info), or 3 (debug); does not affect children
-o DIR, --output DIR      if DOCUMENT is a single file ('file=...'), write output to this directory

Advanced options:

-S OPTS, --sphinx-opts OPTS pass comma-separated OPTS to sphinx-build; must
                            precede OPTS with '=', as in '-S=-q,-aE' or '-S="-q,-aE"'
-U, --update-mtimes         before building reference manual, update
                            modification times for auto-generated reST files
-k, --keep-going            do not abort on errors but continue as much as
                            possible after an error
--all-documents ARG         if ARG is 'reference', list all subdocuments of
                            en/reference. If ARG is 'all', list all main documents

class sage_docbuild.__main__.IntersphinxCache#

Bases: object

Replace sphinx.ext.intersphinx.fetch_inventory by an in-memory cached version.

fetch_inventory(app, uri, inv)#: Return the result of sphinx.ext.intersphinx.fetch_inventory() from a cache if possible. Otherwise, call sphinx.ext.intersphinx.fetch_inventory() and cache the result.

sage_docbuild.__main__.format_columns(lst, align='<', cols=None, indent=4, pad=3, width=80)#

Utility function that formats a list as a simple table and returns a Unicode string representation.

The number of columns is computed from the other options, unless it’s passed as a keyword argument. For help on Python’s string formatter, see

https://docs.python.org/library/string.html#format-string-syntax

sage_docbuild.__main__.get_formats()#: Return a list of output formats the Sage documentation builder will accept on the command-line.

sage_docbuild.__main__.help_commands(name='all')#: Append and return a tabular list of commands, if any, the Sage documentation builder can run on the indicated document. The default is to list all commands for all documents.

sage_docbuild.__main__.help_description(s='', compact=False)#

Append and return a brief description of the Sage documentation builder.

If ‘compact’ is False, the function adds a final newline character.

sage_docbuild.__main__.help_documents()#: Append and return a tabular list of documents, including a shortcut ‘all’ for all documents, available to the Sage documentation builder.

sage_docbuild.__main__.help_examples(s='')#: Append and return some usage examples for the Sage documentation builder.

sage_docbuild.__main__.help_formats()#: Append and return a tabular list of output formats available to the Sage documentation builder.

class sage_docbuild.__main__.help_message_long(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)#

Bases: Action

Print an extended help message for the Sage documentation builder and exits.

class sage_docbuild.__main__.help_message_short(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)#

Bases: Action

Print a help message for the Sage documentation builder.

The message includes command-line usage and a list of options. The message is printed only on the first call. If error is True during this call, the message is printed only if the user hasn’t requested a list (e.g., documents, formats, commands).

sage_docbuild.__main__.help_usage(s='', compact=False)#

Append and return a brief usage message for the Sage documentation builder.

If ‘compact’ is False, the function adds a final newline character.

class sage_docbuild.__main__.help_wrapper(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)#

Bases: Action

A helper wrapper for command-line options to the Sage documentation builder that print lists, such as document names, formats, and document-specific commands.

sage_docbuild.__main__.main()#

sage_docbuild.__main__.setup_logger(verbose=1, color=True)#

Set up a Python Logger instance for the Sage documentation builder.

The optional argument sets logger’s level and message format.

EXAMPLES:

sage: from sage_docbuild.__main__ import setup_logger, logger
sage: setup_logger()
sage: type(logger)
<class 'logging.Logger'>

sage_docbuild.__main__.setup_parser()#: Set up and return a command-line ArgumentParser instance for the Sage documentation builder.