[Docutils-checkins] SF.net SVN: docutils:[9235] trunk/docutils

[<mi...@us...>]

Revision: 9235
          http://sourceforge.net/p/docutils/code/9235
Author:   milde
Date:     2022-11-10 15:02:17 +0000 (Thu, 10 Nov 2022)
Log Message:
-----------
Fix/complement publisher documentation and tests.

API documentation:

- Spell out ampersand (&) as "and".
- Finish description of part "pepnum".
- Add links to LaTeX templates.
- Remove trailing whitespace.

Docstrings:

- Clarify source and output data type for functions using
  "string I/O" (with "string" in the general sense of "`str` or `bytes`").
- Recommend using publish_parts() to get Docutils output as `str`.
- Add "()" to functions so that pydoc HTML rendering generates auto-links.
- Add links to the HTML documentation.

Tests:

- Add test for input/output data types of publish_string().

Modified Paths:
--------------
    trunk/docutils/docs/api/publisher.txt
    trunk/docutils/docutils/core.py
    trunk/docutils/test/test_publisher.py

Modified: trunk/docutils/docs/api/publisher.txt
===================================================================
--- trunk/docutils/docs/api/publisher.txt	2022-11-09 20:51:23 UTC (rev 9234)
+++ trunk/docutils/docs/api/publisher.txt	2022-11-10 15:02:17 UTC (rev 9235)
@@ -97,7 +97,7 @@
 Encodings
 ---------
 
-The default input encoding is UTF-8. 
+The default input encoding is UTF-8.
 A different encoding can be specified with the `input_encoding`_ setting
 or an `explicit encoding declaration` (BOM or special comment).
 The locale encoding may be used as a fallback.
@@ -239,12 +239,12 @@
 
 _`html_subtitle`
     ``parts['html_subtitle']`` contains the document subtitle,
-    including the enclosing ``<h2 class="subtitle">`` & ``</h2>``
+    including the enclosing ``<h2 class="subtitle">`` and ``</h2>``
     tags.
 
 _`html_title`
     ``parts['html_title']`` contains the document title, including the
-    enclosing ``<h1 class="title">`` & ``</h1>`` tags.
+    enclosing ``<h1 class="title">`` and ``</h1>`` tags.
 
 _`meta`
     ``parts['meta']`` contains all ``<meta ... />`` tags.
@@ -255,12 +255,12 @@
 
 _`subtitle`
     ``parts['subtitle']`` contains the document subtitle text and any
-    inline markup.  It does not include the enclosing ``<h2>`` &
+    inline markup.  It does not include the enclosing ``<h2>`` and
     ``</h2>`` tags.
 
 _`title`
     ``parts['title']`` contains the document title text and any inline
-    markup.  It does not include the enclosing ``<h1>`` & ``</h1>``
+    markup.  It does not include the enclosing ``<h1>`` and ``</h1>``
     tags.
 
 
@@ -271,9 +271,12 @@
 plus the following:
 
 _`pepnum`
-    ``parts['pepnum']`` contains
+    ``parts['pepnum']`` contains the PEP number
+    (extracted from the `header preamble`__).
 
+    __ https://peps.python.org/pep-0001/#pep-header-preamble
 
+
 S5/HTML Writer
 ``````````````
 
@@ -291,7 +294,8 @@
 Parts Provided by the LaTeX2e Writer
 ------------------------------------
 
-See the template files for examples how these parts can be combined
+See the template files default.tex_, titlepage.tex_, titlingpage.tex_,
+and xelatex.tex_ for examples how these parts can be combined
 into a valid LaTeX document.
 
 abstract
@@ -356,7 +360,16 @@
 
 titledata
     ``parts['titledata]`` contains the combined title data in
-    ``\title``, ``\author``, and ``\data`` macros.
+    ``\title``, ``\author``, and ``\date`` macros.
 
     With ``--use-latex-docinfo``, this includes the 'author',
     'organization', 'contact', 'address' and 'date' docinfo items.
+
+.. _default.tex:
+   https://docutils.sourceforge.io/docutils/writers/latex2e/default.tex
+.. _titlepage.tex:
+   https://docutils.sourceforge.io/docutils/writers/latex2e/titlepage.tex
+.. _titlingpage.tex:
+   https://docutils.sourceforge.io/docutils/writers/latex2e/titlingpage.tex
+.. _xelatex.tex:
+   https://docutils.sourceforge.io/docutils/writers/latex2e/xelatex.tex

Modified: trunk/docutils/docutils/core.py
===================================================================
--- trunk/docutils/docutils/core.py	2022-11-09 20:51:23 UTC (rev 9234)
+++ trunk/docutils/docutils/core.py	2022-11-10 15:02:17 UTC (rev 9235)
@@ -377,7 +377,7 @@
     output file paths taken automatically from the command line).  Return the
     encoded string output also.
 
-    Parameters: see `publish_programmatically` for the remainder.
+    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
@@ -404,7 +404,7 @@
     Set up & run a `Publisher` for programmatic use with file-like I/O.
     Return the encoded string output also.
 
-    Parameters: see `publish_programmatically`.
+    Parameters: see `publish_programmatically()`.
     """
     output, pub = publish_programmatically(
         source_class=io.FileInput, source=source, source_path=source_path,
@@ -430,18 +430,27 @@
     """
     Set up & run a `Publisher` for programmatic use with string I/O.
 
-    `source` and return value may be `bytes` or `str` objects.
+    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", see below).
 
-    For `bytes` output, set the "output_encoding" setting to the
-    desired encoding. For `str` output, set it to 'unicode', e.g.::
+    To get Docutils output as `str` instance, use `publish_parts()`::
 
-        publish_string(..., settings_overrides={'output_encoding': 'unicode'})
+      output = publish_parts(...)['whole']
 
-    Beware that the "output_encoding" setting may also affect the content
+    or set `output_encoding`_ to the pseudo encoding name "unicode", e.g.::
+
+      publish_string(..., settings_overrides={'output_encoding': 'unicode'})
+
+    Beware that the `output_encoding`_ setting may affect the content
     of the output (e.g. an encoding declaration in HTML or XML or the
     representation of characters as LaTeX macro vs. literal character).
 
-    Parameters: see `publish_programmatically`.
+    Parameters: see `publish_programmatically()`.
+
+    .. _output_encoding:
+        https://docutils.sourceforge.io/docs/user/config.html#output-encoding
     """
     warnings.warn('The return type of publish_string will change to '
                   '"str" from Docutils 0.21.', FutureWarning, stacklevel=2)
@@ -478,7 +487,7 @@
 
         publish_bytes(..., settings_overrides={'input_encoding': 'latin1'})
 
-    Parameters: see `publish_programmatically`.
+    Parameters: see `publish_programmatically()`.
 
     Provisional.
     """
@@ -505,12 +514,20 @@
                   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, and values are Unicode strings;
-    encoding is up to the client.  For programmatic use with string I/O.
+    Dictionary keys are the names of parts.
+    Dictionary values are `str` instances; encoding is up to the client,
+    e.g.::
 
-    Parameters: see `publish_programmatically`.
+       parts = publish_parts(...)
+       body = parts['body'].encode(parts['encoding'])
+
+    Parameters: see `publish_programmatically()`.
+
+    .. _document parts:
+        https://docutils.sourceforge.io/docs/api/publisher.html
+        #publish-parts-details
     """
     output, pub = publish_programmatically(
         source=source, source_path=source_path, source_class=source_class,
@@ -536,7 +553,7 @@
     """
     Set up & run a `Publisher` for programmatic use. Return a document tree.
 
-    Parameters: see `publish_programmatically`.
+    Parameters: see `publish_programmatically()`.
     """
     _output, pub = publish_programmatically(
         source=source, source_path=source_path,
@@ -578,7 +595,7 @@
     Parameters: `document` is a `docutils.nodes.document` object, an existing
     document tree.
 
-    Other parameters: see `publish_programmatically`.
+    Other parameters: see `publish_programmatically()`.
     """
     reader = doctree.Reader(parser_name='null')
     pub = Publisher(reader, None, writer,
@@ -613,7 +630,7 @@
     This is just like publish_cmdline, except that it uses
     io.BinaryFileOutput instead of io.FileOutput.
 
-    Parameters: see `publish_programmatically` for the remainder.
+    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

Modified: trunk/docutils/test/test_publisher.py
===================================================================
--- trunk/docutils/test/test_publisher.py	2022-11-09 20:51:23 UTC (rev 9234)
+++ trunk/docutils/test/test_publisher.py	2022-11-10 15:02:17 UTC (rev 9235)
@@ -70,7 +70,29 @@
             core.publish_cmdline(argv=['data/include.txt', 'nonexisting/path'],
                                  settings_overrides={'traceback': True})
 
+    def test_publish_string(self):
+        # Transparently decode `bytes` source (with "input_encoding" setting)
+        # default: auto-detect, fallback utf-8
+        # Output is encoded according to "output_encoding" setting.
+        settings = {'_disable_config': True,
+                    'datestamp': False}
+        source = 'test → me'
+        expected = ('<document source="<string>">\n'
+                    '    <paragraph>\n'
+                    '        test → me\n')
+        output = core.publish_string(source.encode('utf-16'),
+                                     settings_overrides=settings)
+        self.assertEqual(output.decode('utf-8'), expected)
 
+        # encoding declaration in source
+        source = '.. encoding: latin1\n\nGrüße'
+        # don't encode output (return `str`)
+        settings['output_encoding'] = 'unicode'
+        output = core.publish_string(source.encode('utf-16'),
+                                     settings_overrides=settings)
+        self.assertTrue(output.endswith('Grüße\n'))
+
+
 class PublishDoctreeTestCase(unittest.TestCase, docutils.SettingsSpec):
 
     settings_default_overrides = {

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.