See how automatically generated documentation from Python source code looks like with the Awesome Theme.
This is the Docutils (Python Documentation Utilities) package.
__init__.py: Contains component base classes, exception classes, and Docutils version information.
core.py: Contains the
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.
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
Reportersystem 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.
Base class for Docutils components.
Name of the component type (‘reader’, ‘parser’, ‘writer’). Override in subclasses.
formatsupported by this component?
To be used by transforms to ask the dependent component if it supports a certain input context or output format.
Runtime setting specification base class.
SettingsSpec subclass objects used by
The name of the config file section specific to this component (lowercase, no brackets). Override in subclasses.
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_sectionare to be overlaid on top of the settings from these sections. The “general” section is assumed implicitly. Override in subclasses.
Settings containing filesystem paths. Override in subclasses. Settings listed here are to be interpreted relative to the current working directory.
A dictionary of auxiliary defaults, to override defaults for settings defined in other components’
setting_specs. Override in subclasses.
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.
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
Nonewhich implies no group, just a list of single options).
Description (string or
A sequence of option tuples. Each consists of:
Help text (string)
List of option strings (e.g.
Dictionary of keyword arguments sent to the OptionParser/OptionGroup
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_booleanfunction, 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
See the optparse docs for more details.
More triples of group title, description, options, as many times as needed. Thus,
settings_spectuples can be simply concatenated.
Runtime transform specification base class.
TransformSpec subclass objects used by
Transforms required by this class. Override in subclasses.
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.referencesare unable to find a correct target. The list should contain functions which will try to resolve unknown references, with the following signature:default
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:default
del node['refname'] node.resolved = 1
Each function must have a “priority” attribute which will affect the order the unknown_reference_resolvers are run:default
reference_resolver.priority = 100
Override in subclasses.
VersionInfo(major=0, minor=0, micro=0, releaselevel='final', serial=0, release=True)[source]
Abstract base class of nodes in a document tree.
Traverse a tree of
Nodeobjects, calling the
visitorwhen 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.
TreePruningExceptionsubclasses may be raised (
NodeVisitorobject, containing a
visitimplementation for each
Return true if we should stop the traversal.
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:
An option list (docutils)
Sphinx comes with the
option directive. This renders every option
into its own element, including permalinks:
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.