Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[10393] trunk/docutils
|
From: <mi...@us...> - 2026-08-21 08:27:18
|
Revision: 10393
http://sourceforge.net/p/docutils/code/10393
Author: milde
Date: 2026-08-21 08:27:15 +0000 (Fri, 21 Aug 2026)
Log Message:
-----------
Deprecate obsolete parts of PEP processing.
Since several years, PEPs are no longer generated using Docutils' "rst2pephtml"
but a Sphinx with https://github.com/python/peps/tree/main/pep_sphinx_extensions.
We keep the PEP reader and writer as a way for PEP authors to easily preview
their drafts and edits (when restricting the rST content to the directives and
roles supported by Docutils).
Deprecate the `--no-random`, `--pep-home`, and `--python-home` settings
of the "pep_html" writer and hide them from the command line help.
Also deprecate the `transforms.peps.PEPZero` and `transforms.peps.PEPZeroSpecial`
classes. (PEP 0 is no longer generated from a rST source.)
Announce removals in Docutils 2.0.
Modified Paths:
--------------
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/user/config.rst
trunk/docutils/docutils/transforms/peps.py
trunk/docutils/docutils/writers/pep_html/__init__.py
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2026-08-20 22:07:10 UTC (rev 10392)
+++ trunk/docutils/RELEASE-NOTES.rst 2026-08-21 08:27:15 UTC (rev 10393)
@@ -148,6 +148,15 @@
* Drop short option ``-e`` in Docutils 2.0.
Use the long equivalent ``--error-encoding``.
+* Remove the configuration settings `no_random`, `pep_home`, and
+ `python_home` of the "pep_html" writer in Docutils 2.0.
+ The first two are ignored since Docutils 0.19, the Python home URL
+ is pretty stable by now and can be adapted in a custom template.
+
+ Remove `transforms.peps.PEPZero` and `transforms.peps.PEPZeroSpecial`
+ in Docutils 2.0.
+ PEP 0 (the PEP index) is no longer generated from a rST source.
+
* Remove the "reader_name", "parser_name", and "writer_name" arguments of
`core.Publisher.__init__()` and the `core.publish_*()` convenience
functions as well as the "parser_name" argument of `Reader.__init__()`
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2026-08-20 22:07:10 UTC (rev 10392)
+++ trunk/docutils/docs/user/config.rst 2026-08-21 08:27:15 UTC (rev 10393)
@@ -1444,8 +1444,8 @@
Path [#pwd]_ to template file, which must be encoded in UTF-8.
See also `template [latex writers]`_.
-:Default: "template.txt" in the writer's directory (installed automatically)
- For the exact machine-specific path, use the ``--help`` option).
+:Default: "template.txt" in the writer's directory (installed automatically).
+ [#machine-specific-path]_
:Option: ``--template``.
@@ -1569,29 +1569,33 @@
.. class:: run-in narrow
:`initial_header_level`_: 1 (for "<h1>").
-:`stylesheet_path <stylesheet_path [html writers]_>`__: "pep.css".
+:`stylesheet_path <stylesheet_path [html writers]_>`__:
+ ``docutils/writers/pep_html/pep.css`` in the installation directory.
+ [#machine-specific-path]_
:`template <template [html writers]_>`__:
``docutils/writers/pep_html/template.txt`` in the installation directory.
- For the exact machine-specific path, use the ``--help`` option.
+ [#machine-specific-path]_
no_random
"""""""""
-Do not use a random banner image. Mainly used to get predictable
-results when testing.
+Ignored since Docutils 0.19. Will be removed in Docutils 2.0.
-*Default*: None (use random banner). *Options*: ``--no-random`` (hidden).
+*Default*: None. *Options*: ``--no-random`` (hidden).
pep_home
""""""""
-Home URL prefix for PEPs.
+Ignored since Docutils 0.19. Will be removed in Docutils 2.0.
-*Default*: "." (current directory). *Option*: ``--pep-home``.
+*Default*: "." *Option*: ``--pep-home`` (hidden).
python_home
"""""""""""
Python's home URL.
+Deprecated (if required, the URL can be adapted in a custom `template
+<template [html writers]_>`__).
+Will be removed in Docutils 2.0.
-*Default*: "https://www.python.org". *Option*: ``--python-home``.
+*Default*: "https://www.python.org". *Option*: ``--python-home`` (hidden).
[s5_html writer]
@@ -1606,8 +1610,7 @@
:compact_lists_: disable compact lists.
:template__: ``docutils/writers/s5_html/template.txt`` in the
- installation directory. For the exact machine-specific
- path, use the ``--help`` option.
+ installation directory. [#machine-specific-path]_
__ `template [html writers]`_
@@ -2579,9 +2582,13 @@
buildhtml_ application are resolved relative to the directory of
the respective configuration file.
+.. [#machine-specific-path] The ``--help`` command line option shows the
+ actual, machine-specific path.
+
.. [#SectNum] Added by the `SectNum` transform_, if and only if there
is a `"sectnum" directive`_ in the source document.
+
__ https://docs.python.org/3/library/codecs.html#codecs.register
Modified: trunk/docutils/docutils/transforms/peps.py
===================================================================
--- trunk/docutils/docutils/transforms/peps.py 2026-08-20 22:07:10 UTC (rev 10392)
+++ trunk/docutils/docutils/transforms/peps.py 2026-08-21 08:27:15 UTC (rev 10393)
@@ -18,6 +18,8 @@
import os
import re
import time
+import warnings
+
from docutils import nodes, utils, languages
from docutils import DataError
from docutils.transforms import Transform
@@ -222,10 +224,17 @@
"""
Special processing for PEP 0.
+
+ Deprecated. Will be removed in Docutils 2.0.
"""
default_priority = 760
+ def __init__(self, document, startnode=None) -> None:
+ warnings.warn('The `peps.PEPZero` transform will be removed '
+ 'in Docutils 2.0.', DeprecationWarning, stacklevel=2)
+ super().__init__(document, startnode)
+
def apply(self) -> None:
visitor = PEPZeroSpecial(self.document)
self.document.walk(visitor)
@@ -241,10 +250,17 @@
- Link PEP numbers in the second column of 4-column tables to the PEPs
themselves.
+
+ Deprecated. Will be removed in Docutils 2.0.
"""
pep_url = Headers.pep_url
+ def __init__(self, document, startnode=None) -> None:
+ warnings.warn('The `peps.PEPZeroSpecial` transform will be removed '
+ 'in Docutils 2.0.', DeprecationWarning, stacklevel=2)
+ super().__init__(document, startnode)
+
def unknown_visit(self, node) -> None:
pass
Modified: trunk/docutils/docutils/writers/pep_html/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/pep_html/__init__.py 2026-08-20 22:07:10 UTC (rev 10392)
+++ trunk/docutils/docutils/writers/pep_html/__init__.py 2026-08-21 08:27:15 UTC (rev 10393)
@@ -32,19 +32,18 @@
os.path.join(os.path.dirname(__file__), default_template))
settings_spec = html4css1.Writer.settings_spec + (
- 'PEP/HTML Writer Options',
+ 'PEP/HTML Writer Option Defaults',
'For the PEP/HTML writer, the default value for the --stylesheet-path '
'option is "%s", and the default value for --template is "%s". '
'See HTML Writer Options above.'
% (default_stylesheet_path, default_template_path),
- (('Python\'s home URL. Default is "https://www.python.org".',
+ ((frontend.SUPPRESS_HELP, # deprecated
['--python-home'],
{'default': 'https://www.python.org', 'metavar': '<URL>'}),
- ('Home URL prefix for PEPs. Default is "." (current directory).',
+ (frontend.SUPPRESS_HELP, # ignored since Docutils 0.19 (2022-07-05)
['--pep-home'],
{'default': '.', 'metavar': '<URL>'}),
- # For testing.
- (frontend.SUPPRESS_HELP,
+ (frontend.SUPPRESS_HELP, # ignored since Docutils 0.19 (2022-07-05)
['--no-random'],
{'action': 'store_true', 'validator': frontend.validate_boolean}),))
@@ -64,20 +63,10 @@
settings = self.document.settings
pyhome = settings.python_home
subs['pyhome'] = pyhome
- subs['pephome'] = settings.pep_home
- if pyhome == '..':
- subs['pepindex'] = '.'
- else:
- subs['pepindex'] = pyhome + '/dev/peps'
index = self.document.first_child_matching_class(nodes.field_list)
header = self.document[index]
self.pepnum = header[0][1].astext()
subs['pep'] = self.pepnum
- if settings.no_random:
- subs['banner'] = 0
- else:
- import random
- subs['banner'] = random.randrange(64)
try:
subs['pepnum'] = '%04i' % int(self.pepnum)
except ValueError:
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
