Sphinx build script

This is Sage’s version of the sphinx-build script. We redirect stdout and stderr to our own logger, and remove some unwanted chatter.

class sage_docbuild.sphinxbuild.KnownCitation(labels)[source]

Bases: object

Match the warning about a citation that Sage defines.

A single file is documented without the multidocs extension, hence without the bibliography of the reference manual, so a citation of it - and most Sage files cite something - has nothing to resolve against; see #29651. Ignoring every such warning would hide the citations that are misspelled, which are the ones worth reporting, so the labels that the sources define are consulted instead; see citation_labels().

Instances answer to search(), as the compiled patterns they are used among do.

EXAMPLES:

sage: from sage_docbuild.sphinxbuild import KnownCitation
sage: known = KnownCitation({'Cohen1996'})
sage: bool(known.search('WARNING: citation not found: Cohen1996'))
True
sage: bool(known.search('WARNING: citation not found: Cohen1997'))
False
sage: bool(known.search('WARNING: citation not found: cohen1996'))
True

>>> from sage.all import *
>>> from sage_docbuild.sphinxbuild import KnownCitation
>>> known = KnownCitation({'Cohen1996'})
>>> bool(known.search('WARNING: citation not found: Cohen1996'))
True
>>> bool(known.search('WARNING: citation not found: Cohen1997'))
False
>>> bool(known.search('WARNING: citation not found: cohen1996'))
True

from sage_docbuild.sphinxbuild import KnownCitation
known = KnownCitation({'Cohen1996'})
bool(known.search('WARNING: citation not found: Cohen1996'))
bool(known.search('WARNING: citation not found: Cohen1997'))
bool(known.search('WARNING: citation not found: cohen1996'))

Sphinx colors what it writes to a terminal, and the label is read past the escape sequences:

sage: bool(known.search(
....:     '\x1b[91mWARNING: citation not found: Cohen1996\x1b[39;49;00m'))
True

>>> from sage.all import *
>>> bool(known.search(
...     '\x1b[91mWARNING: citation not found: Cohen1996\x1b[39;49;00m'))
True

bool(known.search(
    '\x1b[91mWARNING: citation not found: Cohen1996\x1b[39;49;00m'))
search(line)[source]
class sage_docbuild.sphinxbuild.SageSphinxLogger(stream, prefix, *, warnings_are_errors=False, ignored_warnings=())[source]

Bases: object

This implements the file object interface to serve as sys.stdout/sys.stderr replacement.

ansi_escape_sequence = re.compile('\n    \\x1b    # ESC\n    \\[      # CSI sequence starts\n    [0-?]*  # parameter bytes\n    [ -/]*  # intermediate bytes\n    [@-~]   # final byte\n    ', re.VERBOSE)
ansi_escape_sequence_color = re.compile('\n        \\x1b    # ESC\n        \\[      # CSI sequence starts\n        [0-9;]* # parameter bytes\n                # intermediate bytes\n        m       # final byte\n        ', re.VERBOSE)
close()[source]
closed = False
encoding = None
flush()[source]
isatty()[source]
mode = 'w'
name = '<log>'
newlines = None
prefix_len = 9
raise_errors()[source]

Raise an exceptions if any errors have been found while parsing the Sphinx output.

EXAMPLES:

sage: from sys import stdout
sage: from sage_docbuild.sphinxbuild import SageSphinxLogger
sage: logger = SageSphinxLogger(stdout, "doctesting")
sage: logger._log_line("This is a SEVERE error\n")
[doctestin] This is a SEVERE error
sage: logger.raise_errors()
Traceback (most recent call last):
...
OSError: This is a SEVERE error

>>> from sage.all import *
>>> from sys import stdout
>>> from sage_docbuild.sphinxbuild import SageSphinxLogger
>>> logger = SageSphinxLogger(stdout, "doctesting")
>>> logger._log_line("This is a SEVERE error\n")
[doctestin] This is a SEVERE error
>>> logger.raise_errors()
Traceback (most recent call last):
...
OSError: This is a SEVERE error

from sys import stdout
from sage_docbuild.sphinxbuild import SageSphinxLogger
logger = SageSphinxLogger(stdout, "doctesting")
logger._log_line("This is a SEVERE error\n")
logger.raise_errors()
softspace = 0
write(str)[source]
writelines(sequence)[source]
sage_docbuild.sphinxbuild.citation_labels(single_file_path=None, single_file_source_root=None)[source]

Return every citation label that the sources of Sage define, or None when the bibliography of the reference manual is not among the sources.

Most citations are collected in a reference manual, and the rest are written in the docstring defining them. Both are parsed as reStructuredText so that examples and comments are not mistaken for definitions. For a file of a second checkout, that checkout is searched as well as the active one.

No answer is cached: a docbuild process can build more than one file, edit a source between builds, or switch the source root in its environment.

EXAMPLES:

sage: from sage_docbuild.sphinxbuild import citation_labels
sage: labels = citation_labels()
sage: labels is None or 'AB2007' in labels
True

>>> from sage.all import *
>>> from sage_docbuild.sphinxbuild import citation_labels
>>> labels = citation_labels()
>>> labels is None or 'AB2007' in labels
True

from sage_docbuild.sphinxbuild import citation_labels
labels = citation_labels()
labels is None or 'AB2007' in labels
sage_docbuild.sphinxbuild.runsphinx(argv, prefix, warnings_are_errors, first_pass, is_inventory, single_file, single_file_path, single_file_source_root)[source]

Run sphinx-build with the arguments argv, logging its output.

INPUT:

  • argv – list of arguments for sphinx-build, without the program name; the last one is the output directory

  • prefix – string used to tag the output lines; defaults to the name of the output directory

  • warnings_are_errors – whether a warning makes the build fail. The LaTeX builder warns about markup that it cannot translate, which is not a reason to stop.

  • first_pass – whether this build runs before the inventories of the other documents have been written

  • is_inventory – whether this build only writes an inventory

  • single_file – whether this build documents one file of its own, outside of any manual

  • single_file_path – the file being documented, when single_file is true

  • single_file_source_root – the import root of single_file_path

A failed build raises OSError, either because Sphinx reported a nonzero exit status, or because it logged a diagnostic that Sage treats as an error.

sage_docbuild.sphinxbuild.single_file_ignored_warnings(single_file_path=None, single_file_source_root=None)[source]

Return the warning patterns that a file documented on its own is built with.

Its citations are the ones that KnownCitation accounts for. Where the sources carry no bibliography to tell one citation from another, all of them are ignored.

EXAMPLES:

sage: from sage_docbuild.sphinxbuild import single_file_ignored_warnings
sage: all(hasattr(pattern, 'search')
....:     for pattern in single_file_ignored_warnings())
True

>>> from sage.all import *
>>> from sage_docbuild.sphinxbuild import single_file_ignored_warnings
>>> all(hasattr(pattern, 'search')
...     for pattern in single_file_ignored_warnings())
True

from sage_docbuild.sphinxbuild import single_file_ignored_warnings
all(hasattr(pattern, 'search')
    for pattern in single_file_ignored_warnings())
sage_docbuild.sphinxbuild.term_width_line(text)[source]