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
--no-preparsed-examples
                      do not show preparsed versions of EXAMPLES blocks
--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
--live-doc            make Sage code blocks live for html FORMAT
--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
--use-cdns            assume internet connection and use CDNs; in particular,
                      use MathJax CDN
-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:

Use these options with care.

-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

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

Python

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

sage_docbuild.__main__.setup_parser()

Set up and return a command-line ArgumentParser instance for the Sage documentation builder.