sphinx_rst_builder

This directive outputs the documentation in RST format with all the sphinx directives converted into pure RST format.

Usage

In conf.py:

extensions = [ ...
    'sphinx_runpython.sphinx_rst_builder',
]

Classes

RstBuilder

class sphinx_runpython.sphinx_rst_builder.RstBuilder(*args, **kwargs)

Defines a RST builder.

default_translator_class

alias of RstTranslator

finish()

Finish the building process.

The default implementation does nothing.

format = 'rst'

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, rst_file_transform)).

get_outfilename(pagename)

Overwrites get_target_uri to control file names.

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.

name = 'rst'

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.

RstTranslator

class sphinx_runpython.sphinx_rst_builder.RstTranslator(document, builder)

Defines a RST translator.

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.

visit_reference(node)

Runs upon entering a reference. Because this class inherits from the TextTranslator class, regularly defined links, such as:

`Some Text`_

.. _Some Text: http://www.some_url.com

were being written as plaintext. This included internal references defined in the standard rst way, such as:

`Some Reference`

.. _Some Reference:

Some Title
----------

To resolve this, if refuri is not included in the node (an internal, non-Sphinx-defined internal uri, the reference is left unchanged.

If internal is not in the node (as for an external, non-Sphinx URI, the reference is rewritten as an inline link, e.g.:

Some Text <http://www.some_url.com>`_

If reftitle is in the node (as in a Sphinx-generated reference), the node is converted to an inline link.

Finally, all other links are also converted to an inline link format.

RstWriter

class sphinx_runpython.sphinx_rst_builder.RstWriter(builder)

Defines a RST writer.

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 RstTranslator