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
--live-doc            make Sage code blocks live for html FORMAT
--warn-links          issue a warning whenever a link is not properly
                      resolved; passes '-n' (nitpicky) to sphinx, except
                      for first-pass (inventory) builds
--check-nested        check picklability of nested classes in DOCUMENT 'reference'
--no-prune-empty-dirs
                      do not prune empty directories in the documentation source
--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__.command_line_args()

Return the arguments that the builder is to parse.

Those of SAGE_DOCBUILD_OPTS come first, so that the ones written on the command line override them.

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

A source tree holding no document at all is listed as the empty table it is, rather than making the help fail.

sage_docbuild.__main__.generate_doc_sources(source_dir)

Write the documentation sources that the repository does not keep.

The installation instructions, the page of every package and the options of the command line are generated from the package metadata and from the parser itself. A distribution ships them and meson writes them into its build directory, but a checkout has neither until something makes them, and Sphinx would only report an include that it cannot read.

Which files the generator writes depends on the package metadata, so it is asked itself whether the tree is complete rather than probed for a file or two: a tree missing, or holding a truncated or an outdated copy of, any one of them builds into an error.

Failing to write them is an error too. The build that follows would report an include that it cannot read, or document the packages of a Sage other than the one asked for, and neither says what went wrong.

sage_docbuild.__main__.get_formats()

Return a list of output formats the Sage documentation builder will accept on the command-line.

The formats are those of any builder, so this needs no document: building one here to ask it would need the options that are still being parsed.

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 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__.sage_root_for(source_dir)

Return a Sage source tree able to generate documentation sources, or None.

A distribution ships the generated sources and has no such tree.

The tree holding source_dir comes first: the sources of a second checkout are generated from the package metadata of that checkout, not from the one that happens to be running.

Every directory on the way up is tried, first of the path with its symbolic links resolved and then of the path as it was given. The resolved tree has to win when a link kept below one checkout points into another one. <root>/src/doc is the usual place, but meson writes into <root>/build/<tag>/src/doc.

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.

sage_docbuild.__main__.setup_parser()

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

sage_docbuild.__main__.source_dir_for_help(argv=None)

Return the documentation sources that the lists printed by the help are read from.

The help is printed while the command line is still being parsed, so a --source that follows the option asking for the list has not reached the parser yet: it is read from argv here, whatever its place, and the default of main() is used when there is none. argv defaults to what main() parses, SAGE_DOCBUILD_OPTS included.

A directory named explicitly is not second-guessed: the lists have to describe the tree that was asked for, or none at all.

An option left without its value is reported rather than passed over, as the parser proper would report it.

Unique long-option abbreviations accepted by argparse designate the same source here.

The end-of-options marker leaves source-looking positional arguments to argparse instead of treating them as options.