SF.net SVN: docutils:[9560 ] trunk/docutils
milde--- via Docutils-checkins <[email protected]>
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 9560
http://sourceforge.net/p/docutils/code/9560
Author: milde
Date: 2024-03-14 10:30:39 +0000 (Thu, 14 Mar 2024)
Log Message:
-----------
Rename new "buildhtml.py" setting "rst_source" to "source".
Keep it simple.
Future-proof (no need to change name in case we add
support for a configurable parser component).
Modified Paths:
--------------
trunk/docutils/RELEASE-NOTES.txt
trunk/docutils/docs/user/config.txt
trunk/docutils/docs/user/tools.txt
trunk/docutils/tools/buildhtml.py
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2024-03-13 18:50:24 UTC (rev 9559)
+++ trunk/docutils/RELEASE-NOTES.txt 2024-03-14 10:30:39 UTC (rev 9560)
@@ -208,7 +208,7 @@
- New configuration setting root_prefix_.
Configurable root directory for included files.
- - New configuration setting rst_sources_ for the "buildhtml.py" application.
+ - New configuration setting sources_ for the "buildhtml.py" application.
- Simpler and more secure `input encoding`_ default behaviour:
@@ -259,7 +259,7 @@
.. _csv-table: docs/ref/rst/directives.html#csv-table
.. _"image" directive: docs/ref/rst/directives.html#image
.. _root_prefix: docs/user/config.html#root-prefix
-.. _rst_sources: docs/user/config.html#rst-sources
+.. _sources: docs/user/config.html#sources
Release 0.20.1 (2023-05-17)
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2024-03-13 18:50:24 UTC (rev 9559)
+++ trunk/docutils/docs/user/config.txt 2024-03-14 10:30:39 UTC (rev 9560)
@@ -112,11 +112,9 @@
* For **boolean** settings (switches), the following values are
recognized (case-independent):
- .. class:: narrow
+ :True: "true", "yes", "on", "1"
+ :False: "false", "no", "off", "0", "" (no value)
- :on: "true", "yes", "on", "1"
- :off: "false", "no", "off", "0", "" (no value)
-
.. _comma-separated:
* **Lists** are specified either comma- or _`colon-separated`:
@@ -135,7 +133,7 @@
*colon-separated*:
- ignore_, prune_, rst_sources_, expose_internals_
+ ignore_, prune_, sources_, expose_internals_
Whitespace around the delimiter is not stripped. Write, e.g., ::
@@ -872,8 +870,6 @@
*Default*: None (disabled). *Option*: ``--smart-quotes``.
-New in Docutils 0.10.
-
.. _SmartQuotes: smartquotes.html
.. _pre-defined quote sets: smartquotes.html#localization
.. _quote characters:
@@ -918,8 +914,6 @@
*Default*: "long". *Option*: ``--syntax-highlight``.
-New in Docutils 0.9.
-
.. _Pygments: https://pygments.org/
.. _code: ../ref/rst/directives.html#code
.. _Pygments-generated stylesheets:
@@ -1262,8 +1256,6 @@
to "MathML" in Docutils 0.22.
:Option: ``--math-output``.
-New in Docutils 0.8.
-
.. _math directive: ../ref/rst/directives.html#math
.. _MathJax: http://www.mathjax.org/
.. _MathML: https://www.w3.org/TR/MathML/
@@ -1719,7 +1711,7 @@
~~~~~~~~~~~~~~
LaTeX code that will be inserted in the document preamble.
Can be used to load packages with options or (re-) define LaTeX
-macros without writing a custom style file (new in Docutils 0.7).
+macros without writing a custom style file.
:Default: writer dependent (see `[latex2e writer]`_, `[xetex writer]`_).
:Option: ``--latex-preamble``.
@@ -2180,7 +2172,7 @@
[buildhtml application]
-----------------------
-buildhtml.py_ generates HTML documents from all reStructuredText source
+buildhtml.py_ generates HTML documents from 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
@@ -2197,33 +2189,32 @@
ignore
~~~~~~
List of glob-style patterns [#globbing]_ (colon-separated_).
+Source files with matching filename are silently ignored.
Values are appended. [#append-values]_
-Matching files are silently ignored.
-
*Default*: ``[]``. *Option*: ``--ignore``.
prune
~~~~~
List of glob-style patterns [#globbing]_ (colon-separated_).
-Values are appended. [#append-values]_
+Matching directories are skipped. Values are appended. [#append-values]_
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 ::
+against the absolute path of to-be-processed directories.
+Example: a directory is pruned if it contains a "docutils.conf" file
+with the lines ::
[buildhtml application]
prune: '.'
The default patterns skip auxiliary directories from Python or
-popular version control tools anywhere. [#]_
+popular version control tools anywhere [#]_.
:Default: ``['/*/.hg', '/*/.bzr', '/*/.git', '/*/.svn',
'/*/.venv', '/*/__pycache__']``.
-:Option: ``--prune``.
+:Option: ``--prune``.
-.. [#] The leading "/" prevents expansion with pwd and
+.. [#] The leading "/" prevents expansion with `pwd`;
``fnmatch('/*')`` matches any absolute path.
recurse
@@ -2230,13 +2221,14 @@
~~~~~~~
Recursively scan subdirectories.
-*Default*: True (recurse). *Options*: ``--recurse``, ``--local``.
+*Default*: True. *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.
+sources
+~~~~~~~
+List of glob-style [#globbing]_ patterns (colon-separated_).
+Files with matching filename are treated as source documents.
+Values in configuration files overwrite the default and are
+overwritten by the command line option.
*Default*: ``['*.rst', '*.txt']``. *Option*: ``--rst-sources``.
@@ -2270,7 +2262,7 @@
`pathlib.PurePath.match()`_).
For example, "``/*.py``" matches "/a/b/c.py".
- Provisional: will use `pathlib.PurePath.match()` once this supports "**".
+ Provisional: may use `pathlib.PurePath.match()` once this supports "**".
.. _fnmatch module:
https://docs.python.org/3/library/fnmatch.html#module-fnmatch
@@ -2296,8 +2288,7 @@
reader
~~~~~~
Reader component name.
-One of "standalone", "pep",
-or the import name of a plug-in reader module.
+One of "standalone", "pep", or the import name of a plug-in reader module.
*Default*: "standalone".
*Option*: ``--reader``
Modified: trunk/docutils/docs/user/tools.txt
===================================================================
--- trunk/docutils/docs/user/tools.txt 2024-03-13 18:50:24 UTC (rev 9559)
+++ trunk/docutils/docs/user/tools.txt 2024-03-14 10:30:39 UTC (rev 9560)
@@ -169,7 +169,7 @@
rst2html test.txt > test.html
-Now open the "``test.html``" file in your favorite browser to see the
+Now open the "``test.html``" file in your favourite browser to see the
results. To get a footer with a link to the source file, date & time
of processing, and links to the Docutils project, add some options::
@@ -238,7 +238,7 @@
rst2s5 slides.txt --output=slides.html
-Now open the "``slides.html``" file in your favorite browser, switch
+Now open the "``slides.html``" file in your favourite browser, switch
to full-screen mode, and enjoy the results.
.. _S5: http://meyerweb.com/eric/tools/s5/
@@ -329,7 +329,7 @@
.. [#copy-theme] Theme files can only be copied by Docutils, if the
output_ destination path is specified.
-
+
.. _output: config.html#output
buildhtml.py
@@ -343,16 +343,16 @@
The ``buildhtml.py`` script can be found in the ``/tools`` directory of
the "docutils" source. It is not included in binary packages. [#]_
-Use ``buildhtml.py`` to generate ``*.html`` from all the reStructuredText
-source files (including PEPs) in each <directory> given, and their
-subdirectories too. (Use the ``--local`` option to skip subdirectories.)
-
Usage::
buildhtml.py [options] [<directory> ...]
-The current directory (including all subdirectories) is chosen by default if
-no directory is specified.
+Use ``buildhtml.py`` to generate ``*.html`` from reStructuredText
+source files in each <directory> given, and their subdirectories too.
+The current directory is chosen by default if no directory is specified.
+Use the ``--local`` option to skip all subdirectories.
+See `[buildhtml application]`_ in `Docutils Configuration`_
+for more specific selection options.
After unpacking the Docutils source package, you can ``cd`` into its root
directory (``docutils-X.Y/`` where "X.Y" is the release version, for
@@ -361,16 +361,11 @@
tools/buildhtml.py
-Some files may generate system messages
-(docs/user/rst/demo.txt contains intentional errors); use the
-``--quiet`` option to suppress all warnings. The ``--config`` option
-ensures that the correct settings are in place (a ``docutils.conf``
-`configuration file`_ in the current directory is picked up
-automatically). Command-line options may be used to override config
-file settings or replace them altogether.
+Some files may generate system messages (docs/user/rst/demo.txt contains
+intentional errors); use the ``--quiet`` option to suppress all warnings.
.. [#] The Debian package "python3-docutils" includes the script
- under the name ``rst-builthtml``.
+ under the name ``rst-buildhtml``.
.. _[buildhtml application]: config.html#buildhtml-application
.. _configuration file: `configuration files`_
Modified: trunk/docutils/tools/buildhtml.py
===================================================================
--- trunk/docutils/tools/buildhtml.py 2024-03-13 18:50:24 UTC (rev 9559)
+++ trunk/docutils/tools/buildhtml.py 2024-03-14 10:30:39 UTC (rev 9560)
@@ -47,7 +47,7 @@
prune_default = ['/*/.hg', '/*/.bzr', '/*/.git', '/*/.svn',
'/*/.venv', '/*/__pycache__']
- rst_sources_default = ['*.rst', '*.txt']
+ sources_default = ['*.rst', '*.txt']
# Can't be included in OptionParser below because we don't want to
# override the base class.
@@ -54,13 +54,28 @@
settings_spec = (
'Build-HTML Options',
None,
- (('Recursively scan subdirectories for files to process. This is '
+ (('Process all files matching any of the given '
+ 'glob-style patterns (separated by colons). '
+ 'This option overwrites the default or config-file values. '
+ f'Default: "{":".join(sources_default)}".',
+ ['--sources'],
+ {'metavar': '<patterns>',
+ 'default': sources_default,
+ 'validator': frontend.validate_colon_separated_string_list}),
+ ('Recursively ignore files matching any of the given '
+ 'glob-style patterns (separated by colons). '
+ 'This option may be used more than once to add more patterns.',
+ ['--ignore'],
+ {'metavar': '<patterns>', 'action': 'append',
+ 'default': [],
+ 'validator': frontend.validate_colon_separated_string_list}),
+ ('Do not scan subdirectories for files to process.',
+ ['--local'], {'dest': 'recurse', 'action': 'store_false'}),
+ ('Recursively scan subdirectories for files to process. This is '
'the default.',
['--recurse'],
{'action': 'store_true', 'default': 1,
'validator': frontend.validate_boolean}),
- ('Do not scan subdirectories for files to process.',
- ['--local'], {'dest': 'recurse', 'action': 'store_false'}),
('Do not process files in <directory> (glob-style patterns, '
'separated by colons). This option may be used '
'more than once to add more patterns. Default: "%s".'
@@ -69,21 +84,6 @@
{'metavar': '<directory>', 'action': 'append',
'validator': frontend.validate_colon_separated_string_list,
'default': prune_default}),
- ('Process all files matching any of the given '
- 'glob-style patterns (separated by colons). '
- 'This option overwrites the default or config-file values. '
- f'Default: "{":".join(rst_sources_default)}".',
- ['--rst-sources'],
- {'metavar': '<patterns>',
- 'default': rst_sources_default,
- 'validator': frontend.validate_colon_separated_string_list}),
- ('Recursively ignore files matching any of the given '
- 'glob-style patterns (separated by colons). '
- 'This option may be used more than once to add more patterns.',
- ['--ignore'],
- {'metavar': '<patterns>', 'action': 'append',
- 'default': [],
- 'validator': frontend.validate_colon_separated_string_list}),
('Docutils writer, one of "html", "html4", "html5". '
'Default: "html" (use Docutils\' default HTML writer).',
['--writer'],
@@ -259,7 +259,7 @@
for name in sorted(filenames):
if match_patterns(name, settings.ignore):
continue
- if match_patterns(name, settings.rst_sources):
+ if match_patterns(name, settings.sources):
self.process_txt(dirpath, name)
def process_txt(self, directory, name):
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.