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

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

Revision: 9544
          http://sourceforge.net/p/docutils/code/9544
Author:   milde
Date:     2024-02-17 10:37:45 +0000 (Sat, 17 Feb 2024)
Log Message:
-----------
Additions for config.txt

Add preface and description of "rst_sources" setting
to section [buildhtml application].

Clarify glob-style pattern behaviour.

Modified Paths:
--------------
    trunk/docutils/docs/user/config.txt
    trunk/docutils/docutils/utils/__init__.py

Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt	2024-02-17 10:37:34 UTC (rev 9543)
+++ trunk/docutils/docs/user/config.txt	2024-02-17 10:37:45 UTC (rev 9544)
@@ -135,7 +135,7 @@
 
 
   *colon-separated*:
-    ignore_, prune_, expose_internals_
+    ignore_, prune_, rst_sources_, expose_internals_
 
     Whitespace around the delimiter is not stripped. Write, e.g., ::
 
@@ -481,7 +481,9 @@
 output
 ------
 
-The path of the output destination. Use "-" for `stdout`.
+The path of the output destination.
+An existing file will be overwritten without warning.
+Use "-" for `stdout`.
 
 Obsoletes the `\<destination>`_ positional argument
 (cf. `Future changes`_ in the RELEASE-NOTES).
@@ -538,10 +540,10 @@
 record_dependencies
 -------------------
 
-Path to a file where Docutils will write a list of files that were
-required to generate the output, e.g. included files or embedded
-stylesheets. [#dependencies]_ [#pwd]_ The format is one path per
-line with forward slashes as separator, the encoding is UTF-8.
+Path to a file where Docutils will write a list of files that
+were required to generate the output, e.g. included files or embedded
+stylesheets. [#dependencies]_  The format is one path per line with
+forward slashes as separator, the encoding is UTF-8.
 
 Set it to "-" in order to write dependencies to stdout.
 
@@ -732,7 +734,7 @@
 warning_stream
 --------------
 
-Path to a file for the output of system messages (warnings). [#pwd]_
+Path [#pwd]_ to a file for the output of system messages (warnings).
 
 *Default*: None (stderr).  *Option*: ``--warnings``.
 
@@ -1290,7 +1292,7 @@
 stylesheet_dirs
 ~~~~~~~~~~~~~~~
 List of directories where stylesheets can be found (comma-separated_).
-Used by the stylesheet_path_ setting when expanding relative path arguments.
+Used by the stylesheet_path_ setting when resolving relative path arguments.
 
 See also `stylesheet_dirs [latex writers]`_.
 
@@ -2124,7 +2126,7 @@
 
 odf_config_file
 ~~~~~~~~~~~~~~~
-Specify a configuration/mapping file path [#pwd]_ for additional ODF options.
+Path [#pwd]_ to a configuration/mapping file for additional ODF options.
 In particular, this file may contain a mapping of default style names to
 names used in the resulting output file.
 See section `How to use custom style names`__ in the
@@ -2137,9 +2139,8 @@
 
 stylesheet
 ~~~~~~~~~~
-Specify a stylesheet URL, used verbatim.
-See section `Styles and Classes`_ in the ODT Writer documentation
-for details.
+Path [#pwd]_ to a style file.  See section `Styles and Classes`_
+in the ODT Writer documentation for details.
 
 :Default: "writers/odf_odt/styles.odt" in the installation directory.
 :Option:  ``--stylesheet``.
@@ -2171,7 +2172,7 @@
 [applications]
 ==============
 
-Some Docutils `front-end tools`_ provide additional settings.
+Some `front end tools`_ provide additional settings.
 
 
 .. _buildhtml:
@@ -2179,6 +2180,14 @@
 [buildhtml application]
 -----------------------
 
+buildhtml.py_ generates HTML documents from all reStructuredText source
+files in a set of directories and their subdirectories.
+All visited directories are scanned for "docutils.conf" files which are
+parsed after the standard configuration files. Path settings [#pwd]_ in
+these files are resolved relative to the respective directory.
+
+The output_ setting is ignored.
+
 dry_run
 ~~~~~~~
 Do not process files, show files that would be processed.
@@ -2187,7 +2196,7 @@
 
 ignore
 ~~~~~~
-List of wildcard (shell globing) patterns (colon-separated_).
+List of glob-style patterns [#globbing]_ (colon-separated_).
 Values are appended. [#append-values]_
 
 Matching files are silently ignored.
@@ -2196,11 +2205,27 @@
 
 prune
 ~~~~~
-List directories to skip (colon-separated_).
+List of glob-style patterns [#globbing]_ (colon-separated_).
 Values are appended. [#append-values]_
 
-*Default*: ['.hg', '.bzr', '.git', '.svn', 'CVS'].  *Option*: ``--prune``.
+Patterns are expanded similar to path settings [#pwd]_ and matched
+against the absolute path of to-be-processed directories. Matching
+directories are skipped. This way, a directory can be marked as
+to-be-pruned by a "./docutils.conf" file containing ::
 
+  [buildhtml application]
+  prune: '.'
+
+The default patterns skip auxiliary directories from Python or
+popular version control tools anywhere. [#]_
+
+:Default: ``['/*/.hg', '/*/.bzr', '/*/.git', '/*/.svn',
+          '/*/.venv', '/*/__pycache__']``.
+:Option: ``--prune``.
+
+.. [#] The leading "/" prevents expansion with pwd and
+       ``fnmatch('/*')`` matches any absolute path.
+
 recurse
 ~~~~~~~
 Recursively scan subdirectories.
@@ -2207,6 +2232,16 @@
 
 *Default*: True (recurse).  *Options*: ``--recurse``, ``--local``.
 
+rst_sources
+~~~~~~~~~~~
+List of glob-style [#globbing]_ patterns specifying files to process as
+reStructuredText source (colon-separated_). Values in configuration files
+overwrite the default and are overwritten by the command line option.
+
+*Default*: ``['*.rst', '*.txt']``.  *Option*: ``--rst-sources``.
+
+New in Docutils 0.21.
+
 silent
 ~~~~~~
 Work silently (no progress messages).
@@ -2229,7 +2264,23 @@
 .. _HTML writer: html.html
 .. _default HTML writer: html.html#html
 
+.. [#globbing] Pattern matching is done with the `fnmatch module`_.
+   It resembles shell-style globbing, but without special treatment
+   of path separators and '.' (in contrast__ to the `glob module`_ and
+   `pathlib.PurePath.match()`_).
+   For example, "``/*.py``" matches "/a/b/c.py".
 
+   Provisional: will use `pathlib.PurePath.match()` once this supports "**".
+
+.. _fnmatch module:
+    https://docs.python.org/3/library/fnmatch.html#module-fnmatch
+.. _glob module:
+    https://docs.python.org/3/library/glob.html#module-glob
+.. _pathlib.PurePath.match():
+    https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.match
+__ https://github.com/python/cpython/issues/106747
+
+
 [docutils application]
 --------------------------
 
@@ -2236,9 +2287,8 @@
 Docutils' `generic front end`_ tool allows combining “reader”, “parser”,
 and “writer” components from the Docutils package or 3rd party plug-ins.
 
-| New in 0.17. Config file support added in 0.18.
-  Renamed in 0.19 (the old section name "docutils-cli application"
-  is kept as alias).
+| New in 0.17. Config file support added in 0.18. Renamed in 0.19
+  (the old section name "docutils-cli application" is kept as alias).
 | Support for reader/parser import names added in 0.19.
 
 .. _generic front end: tools.html#generic-command-line-front-end
@@ -2290,15 +2340,17 @@
 
 config
 ~~~~~~
-Path [#pwd]_ to a configuration file to read (if it exists).
-Settings override defaults and earlier settings.  The config
-file is processed immediately.  Multiple ``--config`` options may
-be specified; each will be processed in turn.
+Path to an additional configuration file.
+The file is processed immediately (if it exists) with
+settings overriding defaults and earlier settings.
 
 Filesystem path settings [#pwd]_ contained within the config file will be
 interpreted relative to the config file's location (*not* relative to the
 current working directory).
 
+Multiple ``--config`` options may be specified;
+each will be processed in turn.
+
 *Default*: None.  *Option*: ``--config``.
 
 
@@ -2408,6 +2460,9 @@
 .. _option lists: ../ref/rst/restructuredtext.html#option-lists
 .. _tables: ../ref/rst/restructuredtext.html#tables
 
+.. _front end tools: tools.html
+.. _buildhtml.py: tools.html#buildhtml-py
+
 .. _BCP 47: https://www.rfc-editor.org/rfc/bcp/bcp47.txt
 .. _Error Handlers:
     https://docs.python.org/3/library/codecs.html#error-handlers

Modified: trunk/docutils/docutils/utils/__init__.py
===================================================================
--- trunk/docutils/docutils/utils/__init__.py	2024-02-17 10:37:34 UTC (rev 9543)
+++ trunk/docutils/docutils/utils/__init__.py	2024-02-17 10:37:45 UTC (rev 9544)
@@ -503,11 +503,12 @@
 
     Differences to `pathlib.PurePath.relative_to(other)`:
 
-    * Object oriented interface.
+    * pathlib offers an object oriented interface.
     * `source` expects path to a FILE while `other` expects a DIRECTORY.
-    * No default value for `other`.
-    * Raise ValueError if relative path cannot be determined.
-    * Fails if target is not a subpath of `other` (no ".." inserted).
+    * `target` defaults to the cwd, no default value for `other`.
+    * `relative_path()` always returns a path (relative or absolute),
+      while `PurePath.relative_to()` raises a ValueError
+      if `target` is not a subpath of `other` (no ".." inserted).
     """
     source_parts = os.path.abspath(source or type(target)('dummy_file')
                                    ).split(os.sep)

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