SF.net SVN: docutils:[9993] trunk/docutils
milde--- via Docutils-checkins <[email protected]>
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 9993
http://sourceforge.net/p/docutils/code/9993
Author: milde
Date: 2024-12-04 13:32:20 +0000 (Wed, 04 Dec 2024)
Log Message:
-----------
Revise output file path configuration setting.
The command-line usage pattern will change in Docutils 1.0 (cf. RELASE-NOTES).
In preparation, the "output" setting was introduced in Docutils 0.20.
As command line option, "--output" is a suitable name, however,
in a wider context, "output" is ambiguous and rather associated with the
actual output than the path to the output file.
Provide `settings.output_path` as "canonical" setting and
`--output` and `--output-path` as command line options.
Let `core.Publisher.set_destination()` synchronize `settings.output_path` with
the legacy settings `settings.output`, and `settings._destination`.
If the `destination_path` argument is specified, it overrides all three
settings and conflicting settings no longer raise an Error.
Use "settings.output_path" instead of the legacy settings in utils, transforms,
and writers.
Fix type hint for "destination" function argument in `Publisher.set_destination()`
(cf. the docstring of `publish_programatically()`).
Modified Paths:
--------------
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/user/config.rst
trunk/docutils/docs/user/latex.rst
trunk/docutils/docs/user/slide-shows.rst
trunk/docutils/docs/user/tools.rst
trunk/docutils/docutils/core.py
trunk/docutils/docutils/frontend.py
trunk/docutils/docutils/transforms/universal.py
trunk/docutils/docutils/utils/__init__.py
trunk/docutils/docutils/writers/_html_base.py
trunk/docutils/docutils/writers/latex2e/__init__.py
trunk/docutils/docutils/writers/s5_html/__init__.py
trunk/docutils/test/data/help/docutils.rst
trunk/docutils/test/data/help/rst2html.rst
trunk/docutils/test/data/help/rst2latex.rst
trunk/docutils/test/test_publisher.py
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2024-12-03 13:12:26 UTC (rev 9992)
+++ trunk/docutils/RELEASE-NOTES.rst 2024-12-04 13:32:20 UTC (rev 9993)
@@ -31,7 +31,7 @@
+ COMMAND [OPTIONS] [SOURCE [SOURCE2 [...]]]
* Stop accepting the DESTINATION positional argument in Docutils 1.0.
- Use ``--output=DESTINATION`` (cf. the "output_" configuration setting)
+ Use ``--output=DESTINATION`` (cf. the "output_path_" configuration setting)
or output redirection.
* Accept the short option ``-o`` for ``--output`` in Docutils 1.0
@@ -226,6 +226,8 @@
Use the long equivalents ``--input-encoding`` and ``--output-encoding``.
(See `command line interface`_ for the rationale.)
+ - Rename configuration setting "output" to "output_path_".
+
Output changes
LaTeX:
Don't wrap references with custom reference-label_ in a ``\hyperref``
@@ -303,6 +305,7 @@
.. _Docutils Document Model:
.. _Docutils XML: docs/ref/doctree.html
+.. _output_path: docs/user/config.html#output
Release 0.21.2 (2024-04-23)
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2024-12-03 13:12:26 UTC (rev 9992)
+++ trunk/docutils/docs/user/config.rst 2024-12-04 13:32:20 UTC (rev 9993)
@@ -232,7 +232,6 @@
.. _ConfigParser.py:
https://docs.python.org/3/library/configparser.html
.. _Python: https://www.python.org/
-.. _RFC 822: https://www.rfc-editor.org/rfc/rfc822.txt
__ ../api/runtime-settings.html#active-sections
@@ -471,23 +470,23 @@
*Default*: "en" (English). *Options*: ``--language``, ``-l``.
-output
-------
+output_path
+-----------
-The path of the output destination. Use "-" for `stdout`.
+Output file path or "-" for `stdout`.
.. Caution:: **An existing file will be overwritten** without warning!
-Obsoletes the `_destination`_ positional argument
-(cf. `Future changes`_ in the RELEASE-NOTES).
+Obsoletes the second `positional argument`_ and the internal
+`_destination`_ setting (cf. `Future changes`_ in the RELEASE-NOTES).
-*Default*: None (stdout). *Option*: ``--output``.
+:Default: None (write to stdout).
+:Options: ``--output-path``, ``--output``.
-New in Docutils 0.20.
+New in Docutils 0.20.
+Renamed from "_`output`" to "output_path" in Docutils 0.22.
-.. _Future changes: ../../RELEASE-NOTES.html#future-changes
-
output_encoding
---------------
@@ -1325,7 +1324,7 @@
List of paths to CSS stylesheets (comma-separated_). Relative paths are
expanded if a matching file is found in the stylesheet_dirs__.
If embed_stylesheet__ is False, paths are rewritten relative to
-the output_ file (if specified) or the current work directory.
+the output_path_ (if specified) or the current work directory.
See also `stylesheet_path [latex writers]`_.
@@ -1885,8 +1884,7 @@
List of style files (comma-separated_). Relative paths are expanded if a
matching file is found in the stylesheet_dirs__.
If embed_stylesheet__ is False, paths are rewritten relative to
-the output file (if output_ or `_destination`_ are specified)
-or the current work directory.
+the output_path_ (if specified) or the current work directory.
Overrides also stylesheet__. [#override]_
See also `stylesheet_path [html writers]`_.
@@ -2194,7 +2192,7 @@
parsed after the standard configuration files. Path settings [#pwd]_ in
these files are resolved relative to the respective directory.
-The output_ setting is ignored.
+The output_path_ setting is ignored.
dry_run
~~~~~~~
@@ -2394,10 +2392,9 @@
_destination
~~~~~~~~~~~~
-Path to output destination, set from `positional arguments`_
-or the output_ setting.
+Path to the output file, set from `positional arguments`_.
-Deprecated, obsoleted by the output_ setting. Will be removed
+Deprecated, obsoleted by the output_path_ setting. Will be removed
in Docutils 2.0 (cf. `Future changes`_ in the RELEASE-NOTES).
*Default*: None (stdout). *Option*: ``--output``.
@@ -2569,8 +2566,11 @@
.. _front-end tool:
.. _front-end tools: tools.html
.. _buildhtml.py: tools.html#buildhtml-py
+.. _positional argument:
.. _positional arguments: tools.html#usage-pattern
+.. _Future changes: ../../RELEASE-NOTES.html#future-changes
+
.. _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/docs/user/latex.rst
===================================================================
--- trunk/docutils/docs/user/latex.rst 2024-12-03 13:12:26 UTC (rev 9992)
+++ trunk/docutils/docs/user/latex.rst 2024-12-04 13:32:20 UTC (rev 9993)
@@ -1789,7 +1789,7 @@
The encoding of the LaTeX source file is Docutils' *output* encoding
but LaTeX' *input* encoding.
-Option: output-encoding_
+Option: output_encoding_
``--output-encoding=OUTPUT-ENCODING``
Default:
@@ -1824,7 +1824,7 @@
(where *n* is the Unicode page-number) to the style sheet might help.
.. _LaTeX Unicode: http://www.unruh.de/DniQ/latex/unicode/
-.. _output-encoding: config.html#output-encoding
+.. _output_encoding: config.html#output-encoding
.. _inputenc: https://ctan.org/pkg/inputenc
.. _ucs: https://ctan.org/pkg/unicode
@@ -2085,7 +2085,7 @@
With "traditional" TeX engines (e.g. pdflatex_):
-- Generate LaTeX code with `output-encoding`_ "utf-8".
+- Generate LaTeX code with the default `output_encoding`_ "utf-8".
- Add the pmboxdraw_ package to the `style sheets`_.
(For shaded boxes also add the `color` package.)
Modified: trunk/docutils/docs/user/slide-shows.rst
===================================================================
--- trunk/docutils/docs/user/slide-shows.rst 2024-12-03 13:12:26 UTC (rev 9992)
+++ trunk/docutils/docs/user/slide-shows.rst 2024-12-04 13:32:20 UTC (rev 9993)
@@ -120,7 +120,7 @@
.. class:: handout
The console script to generate S5 slide shows.
-
+
.. _rst2s5: tools.html#rst2s5
.. topic:: Keyboard Controls
@@ -374,11 +374,11 @@
to an existing theme using the ``--theme-url`` option.
.. [#copy-theme] Theme files can only be copied by Docutils, if the
- output_ destination path is specified.
-
- .. _output: config.html#output
+ `output path`_ is specified.
+ .. _output path: config.html#output-path
+
Generating a Slide Show (2)
===========================
@@ -487,10 +487,10 @@
* http://mozilla.wikicities.com/wiki/Firefox_S5:Designs
* http://lachy.id.au/dev/mozilla/firefox/s5/
* http://www.openlight.com/Python-S5-Theme.tar.gz
-
- Do a web search for "S5
- theme" and you're bound to find plenty of choices.
+ Do a web search for "S5 theme" and you're bound to find plenty
+ of choices.
+
* "``--theme``" option.
.. container:: handout
Modified: trunk/docutils/docs/user/tools.rst
===================================================================
--- trunk/docutils/docs/user/tools.rst 2024-12-03 13:12:26 UTC (rev 9992)
+++ trunk/docutils/docs/user/tools.rst 2024-12-04 13:32:20 UTC (rev 9993)
@@ -331,10 +331,11 @@
<slide-shows.html>`_.
.. [#copy-theme] Theme files can only be copied by Docutils, if the
- output_ destination path is specified.
+ `output path`_ is specified.
-.. _output: config.html#output
+.. _output path: config.html#output-path
+
buildhtml.py
------------
Modified: trunk/docutils/docutils/core.py
===================================================================
--- trunk/docutils/docutils/core.py 2024-12-03 13:12:26 UTC (rev 9992)
+++ trunk/docutils/docutils/core.py 2024-12-04 13:32:20 UTC (rev 9993)
@@ -30,6 +30,7 @@
from docutils.readers import doctree
if TYPE_CHECKING:
+ from typing import TextIO
from docutils.nodes import StrPath
@@ -213,25 +214,33 @@
error_handler=self.settings.input_encoding_error_handler)
def set_destination(self,
- destination: str | None = None,
+ destination: TextIO | None = None,
destination_path: StrPath | None = None,
) -> None:
- if destination_path is None:
- if (self.settings.output and self.settings._destination
- and self.settings.output != self.settings._destination):
- raise SystemExit('The positional argument <destination> is '
- 'obsoleted by the --output option. '
+ # Provisional: the "_destination" and "output" settings
+ # are deprecated and will be ignored in Docutils 2.0.
+ if destination_path is not None:
+ self.settings.output_path = os.fspath(destination_path)
+ else:
+ # check 'output_path' and legacy settings
+ if getattr(self.settings, 'output', None
+ ) and not self.settings.output_path:
+ self.settings.output_path = self.settings.output
+ if (self.settings.output_path and self.settings._destination
+ and self.settings.output_path != self.settings._destination):
+ raise SystemExit('The --output-path option obsoletes the '
+ 'second positional argument (DESTINATION). '
'You cannot use them together.')
- if self.settings.output == '-': # means stdout
- self.settings.output = None
- destination_path = (self.settings.output
- or self.settings._destination)
- else:
- destination_path = os.fspath(destination_path)
- self.settings._destination = destination_path
+ if self.settings.output_path is None:
+ self.settings.output_path = self.settings._destination
+ if self.settings.output_path == '-': # use stdout
+ self.settings.output_path = None
+ self.settings._destination = self.settings.output \
+ = self.settings.output_path
+
self.destination = self.destination_class(
destination=destination,
- destination_path=destination_path,
+ destination_path=self.settings.output_path,
encoding=self.settings.output_encoding,
error_handler=self.settings.output_encoding_error_handler)
Modified: trunk/docutils/docutils/frontend.py
===================================================================
--- trunk/docutils/docutils/frontend.py 2024-12-03 13:12:26 UTC (rev 9992)
+++ trunk/docutils/docutils/frontend.py 2024-12-04 13:32:20 UTC (rev 9993)
@@ -687,7 +687,7 @@
None,
(('Output destination name. Obsoletes the <destination> '
'positional argument. Default: None (stdout).',
- ['--output'], {'metavar': '<destination>'}),
+ ['--output-path', '--output'], {'metavar': '<destination>'}),
('Specify the document title as metadata.',
['--title'], {'metavar': '<title>'}),
('Include a "Generated by Docutils" credit and link.',
Modified: trunk/docutils/docutils/transforms/universal.py
===================================================================
--- trunk/docutils/docutils/transforms/universal.py 2024-12-03 13:12:26 UTC (rev 9992)
+++ trunk/docutils/docutils/transforms/universal.py 2024-12-04 13:32:20 UTC (rev 9993)
@@ -67,7 +67,7 @@
if settings.source_url:
source = settings.source_url
else:
- source = utils.relative_path(settings._destination,
+ source = utils.relative_path(settings.output_path,
settings._source)
text.extend([
nodes.reference('', 'View document source',
Modified: trunk/docutils/docutils/utils/__init__.py
===================================================================
--- trunk/docutils/docutils/utils/__init__.py 2024-12-03 13:12:26 UTC (rev 9992)
+++ trunk/docutils/docutils/utils/__init__.py 2024-12-04 13:32:20 UTC (rev 9993)
@@ -587,7 +587,7 @@
assert not settings.stylesheet, (
'stylesheet and stylesheet_path are mutually exclusive.')
if relative_to is None:
- relative_to = settings._destination
+ relative_to = settings.output_path
return relative_path(relative_to, settings.stylesheet_path)
else:
return settings.stylesheet
Modified: trunk/docutils/docutils/writers/_html_base.py
===================================================================
--- trunk/docutils/docutils/writers/_html_base.py 2024-12-03 13:12:26 UTC (rev 9992)
+++ trunk/docutils/docutils/writers/_html_base.py 2024-12-04 13:32:20 UTC (rev 9993)
@@ -533,7 +533,7 @@
# else link to style file:
if adjust_path:
# rewrite path relative to output (cf. config.html#stylesheet-path)
- path = utils.relative_path(self.settings._destination, path)
+ path = utils.relative_path(self.settings.output_path, path)
return self.stylesheet_link % self.encode(path)
def starttag(self, node, tagname, suffix='\n', empty=False, **attributes):
@@ -645,7 +645,7 @@
__ https://www.rfc-editor.org/rfc/rfc3986.html
"""
- destination = self.settings._destination or ''
+ destination = self.settings.output_path or ''
uri_parts = urllib.parse.urlparse(uri)
if uri_parts.scheme not in ('', 'file'):
raise ValueError('Can only read local images.')
Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py 2024-12-03 13:12:26 UTC (rev 9992)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py 2024-12-04 13:32:20 UTC (rev 9993)
@@ -1440,7 +1440,7 @@
cmd = r'\input{%s}'
if self.settings.stylesheet_path:
# adapt path relative to output (cf. config.html#stylesheet-path)
- return cmd % utils.relative_path(self.settings._destination, path)
+ return cmd % utils.relative_path(self.settings.output_path, path)
return cmd % path.as_posix()
def to_latex_encoding(self, docutils_encoding):
Modified: trunk/docutils/docutils/writers/s5_html/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/s5_html/__init__.py 2024-12-03 13:12:26 UTC (rev 9992)
+++ trunk/docutils/docutils/writers/s5_html/__init__.py 2024-12-04 13:32:20 UTC (rev 9993)
@@ -198,12 +198,12 @@
required_files_copied = {}
# This is a link (URL) in HTML, so we use "/", not os.sep:
self.theme_file_path = 'ui/%s' % settings.theme
- if not settings.output:
+ if not settings.output_path:
raise docutils.ApplicationError(
'Output path not specified, you may need to copy'
' the S5 theme files "by hand" or set the "--output" option.')
dest = os.path.join(
- os.path.dirname(settings.output), 'ui', settings.theme)
+ os.path.dirname(settings.output_path), 'ui', settings.theme)
if not os.path.isdir(dest):
os.makedirs(dest)
default = False
Modified: trunk/docutils/test/data/help/docutils.rst
===================================================================
--- trunk/docutils/test/data/help/docutils.rst 2024-12-03 13:12:26 UTC (rev 9992)
+++ trunk/docutils/test/data/help/docutils.rst 2024-12-04 13:32:20 UTC (rev 9993)
@@ -11,7 +11,8 @@
=======
General Docutils Options
------------------------
---output=<destination> Output destination name. Obsoletes the <destination>
+--output-path=<destination>, --output=<destination>
+ Output destination name. Obsoletes the <destination>
positional argument. Default: None (stdout).
--title=<title> Specify the document title as metadata.
--generator, -g Include a "Generated by Docutils" credit and link.
Modified: trunk/docutils/test/data/help/rst2html.rst
===================================================================
--- trunk/docutils/test/data/help/rst2html.rst 2024-12-03 13:12:26 UTC (rev 9992)
+++ trunk/docutils/test/data/help/rst2html.rst 2024-12-04 13:32:20 UTC (rev 9993)
@@ -12,7 +12,8 @@
=======
General Docutils Options
------------------------
---output=<destination> Output destination name. Obsoletes the <destination>
+--output-path=<destination>, --output=<destination>
+ Output destination name. Obsoletes the <destination>
positional argument. Default: None (stdout).
--title=<title> Specify the document title as metadata.
--generator, -g Include a "Generated by Docutils" credit and link.
Modified: trunk/docutils/test/data/help/rst2latex.rst
===================================================================
--- trunk/docutils/test/data/help/rst2latex.rst 2024-12-03 13:12:26 UTC (rev 9992)
+++ trunk/docutils/test/data/help/rst2latex.rst 2024-12-04 13:32:20 UTC (rev 9993)
@@ -12,7 +12,8 @@
=======
General Docutils Options
------------------------
---output=<destination> Output destination name. Obsoletes the <destination>
+--output-path=<destination>, --output=<destination>
+ Output destination name. Obsoletes the <destination>
positional argument. Default: None (stdout).
--title=<title> Specify the document title as metadata.
--generator, -g Include a "Generated by Docutils" credit and link.
Modified: trunk/docutils/test/test_publisher.py
===================================================================
--- trunk/docutils/test/test_publisher.py 2024-12-03 13:12:26 UTC (rev 9992)
+++ trunk/docutils/test/test_publisher.py 2024-12-04 13:32:20 UTC (rev 9993)
@@ -139,14 +139,18 @@
def test_set_destination(self):
# Exit if `_destination` and `output` settings conflict.
publisher = core.Publisher()
- publisher.get_settings(output='out_name', _destination='out_name')
+ publisher.get_settings(output_path='out_name', _destination='other')
+ with self.assertRaises(SystemExit):
+ publisher.set_destination()
# no conflict if both have same value:
+ publisher.settings._destination = 'out_name'
publisher.set_destination()
# no conflict if both are overridden:
publisher.set_destination(destination_path='winning_dest')
- # ... also sets _destination to 'winning_dest' -> conflict
- with self.assertRaises(SystemExit):
- publisher.set_destination()
+ # "output_path" and legacy settings are set to `destination_path`:
+ self.assertEqual(publisher.settings.output_path, 'winning_dest')
+ self.assertEqual(publisher.settings.output, 'winning_dest')
+ self.assertEqual(publisher.settings._destination, 'winning_dest')
class ConvenienceFunctionTests(unittest.TestCase):
@@ -179,7 +183,7 @@
def test_destination_output_conflict(self):
# Exit if positional argument and --output option conflict.
- settings = {'output': 'out_name'}
+ settings = {'output_path': 'out_name'}
with self.assertRaises(SystemExit):
core.publish_cmdline(argv=['-', 'dest_name'],
settings_overrides=settings)
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