module sphinxext.sphinx_doctree_builder

Inheritance diagram of pyquickhelper.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)[source]

Bases: Builder

Defines a doctree builder.

source on GitHub

Constructor, add a logger.

source on GitHub

__init__(*args, **kwargs)[source]

Constructor, add a logger.

source on GitHub

default_translator_class[source]

alias of DocTreeTranslator

finish()[source]

Finish the building process.

The default implementation does nothing.

format = 'doctree'[source]

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

get_outdated_docs()[source]

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)[source]

Overwrites get_target_uri to control file names.

source on GitHub

get_target_uri(docname, typ=None)[source]

Return the target URI for a document name.

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

init()[source]

Load necessary templates and perform initialization.

source on GitHub

name = 'doctree'[source]

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

prepare_writing(docnames)[source]

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

write_doc(docname, doctree)[source]

Where you actually write something to the filesystem.

class pyquickhelper.sphinxext.sphinx_doctree_builder.DocTreeTranslator(document, builder)[source]

Bases: NodeVisitor, CommonSphinxWriterHelpers

Defines a translator for doctree

source on GitHub

__init__(document, builder)[source]
_format_obj(obj)[source]
unknown_departure(node)[source]

Called before exiting unknown Node types.

Raise exception unless overridden.

unknown_visit(node)[source]

Called when entering unknown Node types.

Raise an exception unless overridden.

class pyquickhelper.sphinxext.sphinx_doctree_builder.DocTreeWriter(builder)[source]

Bases: Writer

Defines a doctree writer.

source on GitHub

__init__(builder)[source]
output = None[source]

Final translated form of document (Unicode string for text, binary string for other forms); set by translate.

settings_defaults = {}[source]

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.', '', ())[source]

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',)[source]

Names for this component. Override in subclasses.

translate()[source]

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[source]

alias of DocTreeTranslator

pyquickhelper.sphinxext.sphinx_doctree_builder.setup(app)[source]

Initializes the doctree builder.

source on GitHub