SF.net SVN: docutils:[9544] trunk/docutils
milde--- via Docutils-checkins <[email protected]>
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
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.
_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins