docutils.core module

Calling the publish_* convenience functions (or instantiating a Publisher object) with component names will result in default behavior. For custom behavior (setting component options), create custom component objects first, and pass them to publish_*/Publisher. See The Docutils Publisher.

class Publisher(reader=None, parser=None, writer=None, source=None, source_class=<class 'docutils.io.FileInput'>, destination=None, destination_class=<class 'docutils.io.FileOutput'>, settings=None)

Bases: object

A facade encapsulating the high-level logic of a Docutils system.

__init__(reader=None, parser=None, writer=None, source=None, source_class=<class 'docutils.io.FileInput'>, destination=None, destination_class=<class 'docutils.io.FileOutput'>, settings=None)

Initial setup. If any of reader, parser, or writer are not specified, set_components() or the corresponding set_...() method should be called with component names (set_reader sets the parser as well).

document

The document tree (docutils.nodes objects).

reader

A docutils.readers.Reader instance.

parser

A docutils.parsers.Parser instance.

writer

A docutils.writers.Writer instance.

source

The source of input data, a docutils.io.Input instance.

source_class

The class for dynamically created source objects.

destination

The destination for docutils output, a docutils.io.Output instance.

destination_class

The class for dynamically created destination objects.

settings

An object containing Docutils settings as instance attributes. Set by self.process_command_line() or self.get_settings().

set_reader(reader_name, parser, parser_name)

Set self.reader by name.

set_writer(writer_name)

Set self.writer by name.

set_components(reader_name, parser_name, writer_name)

setup_option_parser(usage=None, description=None, settings_spec=None, config_section=None, **defaults)

_setup_settings_parser(*args, **kwargs)

get_settings(usage=None, description=None, settings_spec=None, config_section=None, **defaults)

Return settings from components and config files.

Please set components first (self.set_reader & self.set_writer). Use keyword arguments to override component defaults (before updating from configuration files).

Calling this function also sets self.settings which makes self.publish() skip parsing command line options.

process_programmatic_settings(settings_spec, settings_overrides, config_section)

process_command_line(argv=None, usage=None, description=None, settings_spec=None, config_section=None, **defaults)

Parse command line arguments and set self.settings.

Pass an empty sequence to argv to avoid reading sys.argv (the default behaviour).

Set components first (self.set_reader & self.set_writer).

set_io(source_path=None, destination_path=None)

set_source(source=None, source_path=None)

set_destination(destination=None, destination_path=None)

apply_transforms()

publish(argv=None, usage=None, description=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=False)

Process command line options and arguments (if self.settings not already set), run self.reader and then self.writer. Return self.writer’s output.

debugging_dumps()

prompt()

Print info and prompt when waiting for input from a terminal.

report_Exception(error)

report_SystemMessage(error)

report_UnicodeError(error)

publish_cmdline(reader=None, reader_name='standalone', parser=None, parser_name='restructuredtext', writer=None, writer_name='pseudoxml', settings=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=True, argv=None, usage='%prog [options] [<source> [<destination>]]', description='Reads from <source> (default is stdin) and writes to <destination> (default is stdout).  See https://docutils.sourceforge.io/docs/user/config.html for a detailed settings reference.')

Set up & run a Publisher for command-line-based file I/O (input and output file paths taken automatically from the command line). Also return the output as str or bytes (for binary output document formats).

Parameters: see publish_programmatically() for the remainder.

• argv: Command-line argument list to use instead of sys.argv[1:].

• usage: Usage string, output if there’s a problem parsing the command line.

• description: Program description, output for the “–help” option (along with command-line option descriptions).

publish_file(source=None, source_path=None, destination=None, destination_path=None, reader=None, reader_name='standalone', parser=None, parser_name='restructuredtext', writer=None, writer_name='pseudoxml', settings=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=False)

Set up & run a Publisher for programmatic use with file-like I/O. Also return the output as str or bytes (for binary output document formats).

Parameters: see publish_programmatically().

publish_string(source, source_path=None, destination_path=None, reader=None, reader_name='standalone', parser=None, parser_name='restructuredtext', writer=None, writer_name='pseudoxml', settings=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=False)

Set up & run a Publisher for programmatic use with string I/O.

Accepts a bytes or str instance as source.

The output is encoded according to the output_encoding setting; the return value is a bytes instance (unless output_encoding is “unicode”, cf. docutils.io.StringOutput.write()).

Parameters: see publish_programmatically().

This function is provisional because in Python 3 name and behaviour no longer match.

publish_parts(source, source_path=None, source_class=<class 'docutils.io.StringInput'>, destination_path=None, reader=None, reader_name='standalone', parser=None, parser_name='restructuredtext', writer=None, writer_name='pseudoxml', settings=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=False)

Set up & run a Publisher, and return a dictionary of document parts.

Dictionary keys are the names of parts. Dictionary values are str instances; encoding is up to the client, e.g.:

parts = publish_parts(...)
body = parts['body'].encode(parts['encoding'], parts['errors'])

See the API documentation for details on the provided parts.

Parameters: see publish_programmatically().

publish_doctree(source, source_path=None, source_class=<class 'docutils.io.StringInput'>, reader=None, reader_name='standalone', parser=None, parser_name='restructuredtext', settings=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=False)

Set up & run a Publisher for programmatic use. Return a document tree.

Parameters: see publish_programmatically().

publish_from_doctree(document, destination_path=None, writer=None, writer_name='pseudoxml', settings=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=False)

Set up & run a Publisher to render from an existing document tree data structure. For programmatic use with string output (bytes or str, cf. publish_string()).

Note that document.settings is overridden; if you want to use the settings of the original document, pass settings=document.settings.

Also, new document.transformer and document.reporter objects are generated.

Parameters: document is a docutils.nodes.document object, an existing document tree.

Other parameters: see publish_programmatically().

This function is provisional because in Python 3 name and behaviour of the io.StringOutput class no longer match.

publish_cmdline_to_binary(reader=None, reader_name='standalone', parser=None, parser_name='restructuredtext', writer=None, writer_name='pseudoxml', settings=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=True, argv=None, usage='%prog [options] [<source> [<destination>]]', description='Reads from <source> (default is stdin) and writes to <destination> (default is stdout).  See https://docutils.sourceforge.io/docs/user/config.html for a detailed settings reference.', destination=None, destination_class=<class 'docutils.io.BinaryFileOutput'>)

Set up & run a Publisher for command-line-based file I/O (input and output file paths taken automatically from the command line). Also return the output as bytes.

This is just like publish_cmdline, except that it uses io.BinaryFileOutput instead of io.FileOutput.

Parameters: see publish_programmatically() for the remainder.

• argv: Command-line argument list to use instead of sys.argv[1:].

• usage: Usage string, output if there’s a problem parsing the command line.

• description: Program description, output for the “–help” option (along with command-line option descriptions).

publish_programmatically(source_class, source, source_path, destination_class, destination, destination_path, reader, reader_name, parser, parser_name, writer, writer_name, settings, settings_spec, settings_overrides, config_section, enable_exit_status)

Set up & run a Publisher for custom programmatic use.

Return the output (as str or bytes, depending on destination_class, writer, and the “output_encoding” setting) and the Publisher object.

Applications should not need to call this function directly. If it does seem to be necessary to call this function directly, please write to the Docutils-develop mailing list <https://docutils.sourceforge.io/docs/user/mailing-lists.html#docutils-develop>.

Parameters:

• source_class required: The class for dynamically created source objects. Typically io.FileInput or io.StringInput.

• source: Type depends on source_class:

  • If source_class is io.FileInput: Either a file-like object (must have ‘read’ and ‘close’ methods), or None (source_path is opened). If neither source nor source_path are supplied, sys.stdin is used.

  • If source_class is io.StringInput required: The input as either a bytes object (ensure the ‘input_encoding’ setting matches its encoding) or a str object.

• source_path: Type depends on source_class:

  • io.FileInput: Path to the input file, opened if no source supplied.

  • io.StringInput: Optional. Path to the file or name of the object that produced source. Only used for diagnostic output.

• destination_class required: The class for dynamically created destination objects. Typically io.FileOutput or io.StringOutput.

• destination: Type depends on destination_class:

  • io.FileOutput: Either a file-like object (must have ‘write’ and ‘close’ methods), or None (destination_path is opened). If neither destination nor destination_path are supplied, sys.stdout is used.

  • io.StringOutput: Not used; pass None.

• destination_path: Type depends on destination_class:

  • io.FileOutput: Path to the output file. Opened if no destination supplied.

  • io.StringOutput: Path to the file or object which will receive the output; optional. Used for determining relative paths (stylesheets, source links, etc.).

• reader: A docutils.readers.Reader object.

• reader_name: Name or alias of the Reader class to be instantiated if no reader supplied.

• parser: A docutils.parsers.Parser object.

• parser_name: Name or alias of the Parser class to be instantiated if no parser supplied.

• writer: A docutils.writers.Writer object.

• writer_name: Name or alias of the Writer class to be instantiated if no writer supplied.

• settings: A runtime settings (docutils.frontend.Values) object, for dotted-attribute access to runtime settings. It’s the end result of the SettingsSpec, config file, and option processing. If settings is passed, it’s assumed to be complete and no further setting/config/option processing is done.

• settings_spec: A docutils.SettingsSpec subclass or object. Provides extra application-specific settings definitions independently of components. In other words, the application becomes a component, and its settings data is processed along with that of the other components. Used only if no settings specified.

• settings_overrides: A dictionary containing application-specific settings defaults that override the defaults of other components. Used only if no settings specified.

• config_section: A string, the name of the configuration file section for this application. Overrides the config_section attribute defined by settings_spec. Used only if no settings specified.

• enable_exit_status: Boolean; enable exit status at end of processing?

rst2something(writer, documenttype, doc_path='')

rst2html()

rst2html4()

rst2html5()

rst2latex()

rst2man()

rst2odt()

rst2pseudoxml()

rst2s5()

rst2xetex()

rst2xml()