Module documentation

See how automatically generated documentation from Python source code looks like with the Awesome Theme.

Automodule example

This is the Docutils (Python Documentation Utilities) package.

Package Structure

Modules:

• __init__.py: Contains component base classes, exception classes, and Docutils version information.

• core.py: Contains the Publisher class and publish_*() convenience functions.

• frontend.py: Runtime settings (command-line interface, configuration files) processing, for Docutils front-ends.

• io.py: Provides a uniform API for low-level input and output.

• nodes.py: Docutils document tree (doctree) node class library.

• statemachine.py: A finite state machine specialized for regular-expression-based text filters.

Subpackages:

• languages: Language-specific mappings of terms.

• parsers: Syntax-specific input parser modules or packages.

• readers: Context-specific input handlers which understand the data source and manage a parser.

• transforms: Modules used by readers and writers to modify the Docutils document tree.

• utils: Contains the Reporter system warning class and miscellaneous utilities used by readers, writers, and transforms.

  utils/urischemes.py: Contains a complete mapping of known URI addressing scheme names to descriptions.

• utils/math: Contains functions for conversion of mathematical notation between different formats (LaTeX, MathML, text, …).

• writers: Format-specific output translators.

exception docutils.ApplicationError

class docutils.Component

Base class for Docutils components.

component_type = None

Name of the component type (‘reader’, ‘parser’, ‘writer’). Override in subclasses.

supported = ()

Name and aliases for this component. Override in subclasses.

supports(format)

Is format supported by this component?

To be used by transforms to ask the dependent component if it supports a certain input context or output format.

exception docutils.DataError

class docutils.SettingsSpec

Runtime setting specification base class.

SettingsSpec subclass objects used by docutils.frontend.OptionParser.

config_section = None

The name of the config file section specific to this component (lowercase, no brackets). Override in subclasses.

config_section_dependencies = None

A list of names of config file sections that are to be applied before config_section, in order (from general to specific). In other words, the settings in config_section are to be overlaid on top of the settings from these sections. The “general” section is assumed implicitly. Override in subclasses.

relative_path_settings = ()

Settings containing filesystem paths. Override in subclasses. Settings listed here are to be interpreted relative to the current working directory.

settings_default_overrides = None

A dictionary of auxiliary defaults, to override defaults for settings defined in other components’ setting_specs. Override in subclasses.

settings_defaults = None

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 = ()

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.

class docutils.TransformSpec

Runtime transform specification base class.

TransformSpec subclass objects used by docutils.transforms.Transformer.

get_transforms()

Transforms required by this class. Override in subclasses.

unknown_reference_resolvers = ()

List of functions to try to resolve unknown references. Unknown references have a ‘refname’ attribute which doesn’t correspond to any target in the document. Called when the transforms in docutils.transforms.references are unable to find a correct target. The list should contain functions which will try to resolve unknown references, with the following signature:

python

def reference_resolver(node):
    '''Returns boolean: true if resolved, false if not.'''

If the function is able to resolve the reference, it should also remove the ‘refname’ attribute and mark the node as resolved:

python

del node['refname']
node.resolved = 1

Each function must have a “priority” attribute which will affect the order the unknown_reference_resolvers are run:

python

reference_resolver.priority = 100

Override in subclasses.

class docutils.VersionInfo(major=0, minor=0, micro=0, releaselevel='final', serial=0, release=True)

Autoclass example

class docutils.nodes.Node

Abstract base class of nodes in a document tree.

asdom(dom=None)

Return a DOM fragment representation of this Node.

astext()

Return a string representation of this Node.

copy()

Return a copy of self.

deepcopy()

Return a deep copy of self (also copying children).

property document

Return the document root node of the tree containing this Node.

findall(condition=None, include_self=True, descend=True, siblings=False, ascend=False)

Return an iterator yielding nodes following self:

• self (if include_self is true)

• all descendants in tree traversal order (if descend is true)

• the following siblings (if siblings is true) and their descendants (if also descend is true)

• the following siblings of the parent (if ascend is true) and their descendants (if also descend is true), and so on.

If condition is not None, the iterator yields only nodes for which condition(node) is true. If condition is a node class cls, it is equivalent to a function consisting of return isinstance(node, cls).

If ascend is true, assume siblings to be true as well.

If the tree structure is modified during iteration, the result is undefined.

For example, given the following tree:

python

<paragraph>
    <emphasis>      <--- emphasis.traverse() and
        <strong>    <--- strong.traverse() are called.
            Foo
        Bar
    <reference name="Baz" refid="baz">
        Baz

Then tuple(emphasis.traverse()) equals

python

(<emphasis>, <strong>, <#text: Foo>, <#text: Bar>)

and list(strong.traverse(ascend=True) equals

python

[<strong>, <#text: Foo>, <#text: Bar>, <reference>, <#text: Baz>]

line = None

The line number (1-based) of the beginning of this Node in source.

next_node(condition=None, include_self=False, descend=True, siblings=False, ascend=False)

Return the first node in the iterator returned by findall(), or None if the iterable is empty.

Parameter list is the same as of traverse. Note that include_self defaults to False, though.

parent = None

Back-reference to the Node immediately containing this Node.

pformat(indent='    ', level=0)

Return an indented pseudo-XML representation, for test purposes.

Override in subclasses.

previous_sibling()

Return preceding sibling node or None.

source = None

Path or description of the input source which generated this Node.

traverse(condition=None, include_self=True, descend=True, siblings=False, ascend=False)

Return list of nodes following self.

For looping, Node.findall() is faster and more memory efficient.

walk(visitor)

Traverse a tree of Node objects, calling the dispatch_visit() method of visitor when entering each node. (The walkabout() method is similar, except it also calls the dispatch_departure() method before exiting each node.)

This tree traversal supports limited in-place tree modifications. Replacing one node with one or more nodes is OK, as is removing an element. However, if the node removed or replaced occurs after the current node, the old node will still be traversed, and any new nodes will not.

Within visit methods (and depart methods for walkabout()), TreePruningException subclasses may be raised (SkipChildren, SkipSiblings, SkipNode, SkipDeparture).

Parameter visitor: A NodeVisitor object, containing a visit implementation for each Node subclass encountered.

Return true if we should stop the traversal.

walkabout(visitor)

Perform a tree traversal similarly to Node.walk() (which see), except also call the dispatch_departure() method before exiting each node.

Parameter visitor: A NodeVisitor object, containing a visit and depart implementation for each Node subclass encountered.

Return true if we should stop the traversal.

Autofunction example

docutils.nodes.serial_escape(value)

Escape string values that are elements of a list, for serialization.

Command line options

If you want to document command-line options, you have two choices:

• The option directive (Sphinx)

• An option list (docutils)

Option directive

Sphinx comes with the option directive. This renders every option into its own element, including permalinks:

-h, --help

Display a (hopefully) useful message.

-i FILE, --input FILE

Specify an input file.

-v, --verbose

Increase the verbosity.

Option lists

A compact way to display command-line options is built into the docutils module and works in Sphinx too:

-h, --help

Display a helpful message.

-i FILE, --input FILE

Specify an input file.

-v, --verbose

Increase the verbosity.