module sphinxext.sphinx_doctree_builder

Short summary

module pyquickhelper.sphinxext.sphinx_doctree_builder

Defines a sphinx extension to output sphinx doctree.

source on GitHub

Classes

class	truncated documentation
DocTreeBuilder	Defines a doctree builder.
DocTreeTranslator	Defines a translator for doctree
DocTreeWriter	Defines a doctree writer.

Functions

function	truncated documentation
setup	Initializes the doctree builder.

Methods

method	truncated documentation
__init__	Constructor, add a logger.
__init__
__init__
_format_obj
add_text
depart_document
depart_Text
end_state
finish
get_outdated_docs	Return an iterable of input files that are outdated. This method is taken from TextBuilder.get_outdated_docs() …
get_outfilename	Overwrites get_target_uri to control file names.
get_target_uri
handle_page
init	Load necessary templates and perform initialization.
log_unknown
new_state
prepare_writing
translate
unknown_departure
unknown_visit
visit_document
visit_Text
wrap
write_doc

Documentation

Defines a sphinx extension to output sphinx doctree.

source on GitHub

class pyquickhelper.sphinxext.sphinx_doctree_builder.DocTreeBuilder(*args, **kwargs)

Bases: Builder

Defines a doctree builder.

source on GitHub

Constructor, add a logger.

source on GitHub

__init__(*args, **kwargs)

Constructor, add a logger.

source on GitHub

default_translator_class

alias of DocTreeTranslator

finish()

Finish the building process.

The default implementation does nothing.

format = 'doctree'

The builder’s output format, or ‘’ if no document output is produced.

get_outdated_docs()

Return an iterable of input files that are outdated. This method is taken from TextBuilder.get_outdated_docs() with minor changes to support (confval, doctree_file_transform)).

source on GitHub

get_outfilename(pagename)

Overwrites get_target_uri to control file names.

source on GitHub

get_target_uri(docname, typ=None)

Return the target URI for a document name.

typ can be used to qualify the link characteristic for individual builders.

init()

Load necessary templates and perform initialization.

source on GitHub

name = 'doctree'

The builder’s name, for the -b command line option.

prepare_writing(docnames)

A place where you can add logic before write_doc() is run

write_doc(docname, doctree)

Where you actually write something to the filesystem.

class pyquickhelper.sphinxext.sphinx_doctree_builder.DocTreeTranslator(document, builder)

Bases: NodeVisitor, CommonSphinxWriterHelpers

Defines a translator for doctree

source on GitHub

__init__(document, builder)

_format_obj(obj)

unknown_departure(node)

Called before exiting unknown Node types.

Raise exception unless overridden.

unknown_visit(node)

Called when entering unknown Node types.

Raise an exception unless overridden.

class pyquickhelper.sphinxext.sphinx_doctree_builder.DocTreeWriter(builder)

Bases: Writer

Defines a doctree writer.

source on GitHub

__init__(builder)

output = None

Final translated form of document

(str for text, bytes for binary formats); set by translate().

settings_defaults = {}

A dictionary of defaults for settings not in settings_spec (internal settings, intended to be inaccessible by command-line and config file). Override in subclasses.

settings_spec = ('No options here.', '', ())

Runtime settings specification. Override in subclasses.

Defines runtime settings and associated command-line options, as used by docutils.frontend.OptionParser. This is a tuple of:

• Option group title (string or None which implies no group, just a list of single options).

• Description (string or None).

• A sequence of option tuples. Each consists of:

  • Help text (string)

  • List of option strings (e.g. ['-Q', '--quux']).

  • Dictionary of keyword arguments sent to the OptionParser/OptionGroup add_option method.

    Runtime setting names are derived implicitly from long option names (’–a-setting’ becomes settings.a_setting) or explicitly from the ‘dest’ keyword argument.

    Most settings will also have a ‘validator’ keyword & function. The validator function validates setting values (from configuration files and command-line option arguments) and converts them to appropriate types. For example, the docutils.frontend.validate_boolean function, required by all boolean settings, converts true values (‘1’, ‘on’, ‘yes’, and ‘true’) to 1 and false values (‘0’, ‘off’, ‘no’, ‘false’, and ‘’) to 0. Validators need only be set once per setting. See the docutils.frontend.validate_* functions.

    See the optparse docs for more details.

• More triples of group title, description, options, as many times as needed. Thus, settings_spec tuples can be simply concatenated.

supported = ('text',)

Name and aliases for this component. Override in subclasses.

translate()

Do final translation of self.document into self.output. Called from write. Override in subclasses.

Usually done with a docutils.nodes.NodeVisitor subclass, in combination with a call to docutils.nodes.Node.walk() or docutils.nodes.Node.walkabout(). The NodeVisitor subclass must support all standard elements (listed in docutils.nodes.node_class_names) and possibly non-standard elements used by the current Reader as well.

translator_class

alias of DocTreeTranslator

pyquickhelper.sphinxext.sphinx_doctree_builder.setup(app)

Initializes the doctree builder.

source on GitHub