From 494b8d08877fa700a889e3f10af446d8c94ee5e0 Mon Sep 17 00:00:00 2001 From: milde Date: Wed, 12 Apr 2023 15:11:38 +0000 Subject: Update Publisher API documentation. Add links. git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk@9343 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/docs/api/publisher.txt | 77 +++++++++++++++++++++++++++-------------- docutils/docutils/core.py | 12 +++---- 2 files changed, 57 insertions(+), 32 deletions(-) diff --git a/docutils/docs/api/publisher.txt b/docutils/docs/api/publisher.txt index c4dd44d73..89810ffc2 100644 --- a/docutils/docs/api/publisher.txt +++ b/docutils/docs/api/publisher.txt @@ -16,33 +16,38 @@ The ``docutils.core.Publisher`` class is the core of Docutils, managing all the processing and relationships between components. See `PEP 258`_ for an overview of Docutils components. +Configuration_ is done via `runtime settings`_ assembled from several sources. -The ``docutils.core.publish_*()`` convenience functions are the normal -entry points for using Docutils as a library. - -See `Inside A Docutils Command-Line Front-End Tool`_ for an overview -of a typical Docutils front-end tool, including how the Publisher -class is used. +The `Publisher convenience functions`_ are the normal entry points for +using Docutils as a library. .. _PEP 258: ../peps/pep-0258.html -.. _Inside A Docutils Command-Line Front-End Tool: ../howto/cmdline-tool.html Publisher Convenience Functions =============================== +There are several convenience functions in the ``docutils.core`` module. Each of these functions sets up a `docutils.core.Publisher` object, then calls its ``publish()`` method. ``docutils.core.Publisher.publish()`` -handles everything else. There are several convenience functions in -the ``docutils.core`` module: +handles everything else. + +See the module docstring, ``help(docutils.core)``, and the function +docstrings, e.g., ``help(docutils.core.publish_string)``, for details and +a description of the function arguments. + +.. TODO: generate API documentation with Sphinx and add links to it. publish_cmdline() ----------------- -Function for command-line front-end tools, like ``rst2html.py``. There are -several examples in the ``tools/`` directory. A detailed analysis of one -such tool is in `Inside A Docutils Command-Line Front-End Tool`_. +Function for command-line front-end tools, like ``rst2html.py`` with +file I/O. Also returns the output as `bytes` instance. + +There are several examples in the ``tools/`` directory of the Docutils +repository. A detailed analysis of one such tool is in `Inside A Docutils +Command-Line Front-End Tool`_. .. _Inside A Docutils Command-Line Front-End Tool: ../howto/cmdline-tool.html @@ -72,13 +77,14 @@ Output ``"unicode"``. * a `bytes` instance, if the "encode_output" argument is ``True`` and - output_encoding_ is set to an encoding registerd with + output_encoding_ is set to an encoding registered with Python's "codecs_" module (default: "utf-8"). - Calling ``output = bytes(publish_string(…))`` ensures that - ``output`` is a `bytes` instance encoded with output_encoding_. + Calling ``output = bytes(publish_string(…))`` ensures that ``output`` + is a `bytes` instance encoded with the configured output_encoding_ + (matching the encoding indicated inside HTML, XML, and LaTeX documents). -.. [#] Actually an instance of a `str` sub-class with the +.. [#] More precisely, an instance of a `str` sub-class with the output_encoding_ and output_encoding_error_handler_ configuration settings stored as "encoding" and "errors" attributes. @@ -92,25 +98,25 @@ Parse string input (cf. `string I/O`_) into a `Docutils document tree`_ data structure (doctree). The doctree can be modified, pickled & unpickled, etc., and then reprocessed with `publish_from_doctree()`_. -.. _Docutils document tree: ../ref/doctree.html - publish_from_doctree() ---------------------- -Render from an existing document tree data structure (doctree). +Render from an existing `document tree`_ data structure (doctree). Returns the output document as a memory object (cf. `string I/O`_). publish_programmatically() -------------------------- -This function implements common code and is used by `publish_file()`_, -`publish_string()`_, and `publish_parts()`_. +Auxilliary function used by `publish_file()`_, `publish_string()`_, +`publish_doctree()`_, and `publish_parts()`_. It returns a 2-tuple: the output document as memory object (cf. `string I/O`_) and the Publisher object. +.. _publish-parts-details: + publish_parts() --------------- @@ -380,6 +386,20 @@ titledata Configuration ============= +Docutils is configured by runtime settings assembled from several +sources: + +* *settings specifications* of the selected components (reader, parser, + writer), +* *configuration files* (if enabled), and +* *command-line options* (if enabled). + +The individual settings are described in `Docutils Configuration`_. + +Docutils overlays default and explicitly specified values from these +sources such that settings behave the way we want and expect them to +behave. For details, see `Docutils Runtime Settings`_. + To pass application-specific setting defaults to the Publisher convenience functions, use the ``settings_overrides`` parameter. Pass a dictionary of setting names & values, like this:: @@ -389,12 +409,10 @@ a dictionary of setting names & values, like this:: output = publish_string(..., settings_overrides=overrides) Settings from command-line options override configuration file -settings, and they override application defaults. For details, see -`Docutils Runtime Settings`_. See `Docutils Configuration`_ for -details about individual settings. +settings, and they override application defaults. -.. _Docutils Runtime Settings: ./runtime-settings.html -.. _Docutils Configuration: ../user/config.html +Further customization is possible creating custom component +objects and passing *them* to ``publish_*()`` or the ``Publisher``. Encodings @@ -456,6 +474,8 @@ A different encoding can be specified with the `output_encoding`_ setting. This feature is scheduled to be removed in Docutils 1.0. See the `inspecting_codecs`_ package for a possible replacement. + +.. _Inside A Docutils Command-Line Front-End Tool: ../howto/cmdline-tool.html .. _RELEASE-NOTES: ../../RELEASE-NOTES.html#future-changes .. _input_encoding: ../user/config.html#input-encoding .. _preferred encoding: @@ -468,4 +488,9 @@ A different encoding can be specified with the `output_encoding`_ setting. ../ref/rst/restructuredtext.html#auto-symbol-footnotes .. _"contents" directive: ../ref/rst/directives.html#table-of-contents +.. _document tree: +.. _Docutils document tree: ../ref/doctree.html +.. _runtime settings: +.. _Docutils Runtime Settings: ./runtime-settings.html +.. _Docutils Configuration: ../user/config.html .. _inspecting_codecs: https://codeberg.org/milde/inspecting-codecs diff --git a/docutils/docutils/core.py b/docutils/docutils/core.py index 09da78beb..e19d6cefb 100644 --- a/docutils/docutils/core.py +++ b/docutils/docutils/core.py @@ -483,7 +483,7 @@ def publish_parts(source, source_path=None, source_class=io.StringInput, settings_overrides=None, config_section=None, enable_exit_status=False): """ - Set up & run a `Publisher`, and return a dictionary of `document parts`_. + 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, @@ -492,11 +492,11 @@ def publish_parts(source, source_path=None, source_class=io.StringInput, parts = publish_parts(...) body = parts['body'].encode(parts['encoding']) + See the `API documentation`__ for details on the provided parts. + Parameters: see `publish_programmatically()`. - .. _document parts: - https://docutils.sourceforge.io/docs/api/publisher.html - #publish-parts-details + __ https://docutils.sourceforge.io/docs/api/publisher.html#publish-parts """ output, publisher = publish_programmatically( source=source, source_path=source_path, source_class=source_class, @@ -545,8 +545,8 @@ def publish_from_doctree(document, destination_path=None, enable_exit_status=False, auto_encode=True): """ - Set up & run a `Publisher` to render from an existing document - tree data structure, for programmatic use with string output + 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 -- cgit v1.2.1