SF.net SVN: docutils:[10270 ] trunk/docutils
milde--- via Docutils-checkins <[email protected]> Wed, 03 Dec 2025 11:38:54 +0000
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 10270
http://sourceforge.net/p/docutils/code/10270
Author: milde
Date: 2025-12-03 11:38:54 +0000 (Wed, 03 Dec 2025)
Log Message:
-----------
New value "auto" for "initial_header_level" config setting.
``initial_header_level: auto`` tells the HTML writer to use
<h2> if there is a document title, else <h1>.
This ensures a valid "outline" of the HTML document (top heading level 1,
nested headings one level below their parent).
Cf. https://html.spec.whatwg.org/multipage/sections.html#outline
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/docs/user/config.rst
trunk/docutils/docutils/writers/_html_base.py
trunk/docutils/docutils/writers/html4css1/__init__.py
trunk/docutils/docutils/writers/html5_polyglot/__init__.py
trunk/docutils/test/test_writers/test_html5_polyglot_parts.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2025-12-02 19:48:48 UTC (rev 10269)
+++ trunk/docutils/HISTORY.rst 2025-12-03 11:38:54 UTC (rev 10270)
@@ -17,6 +17,11 @@
Release 0.22.4b1 (unpublished)
==============================
+* docutils/io.py
+
+ - Ensure `FileInput.read()` returns a `str` (decode if `source.read`
+ returns `bytes`. Fixes bug #514.
+
* docutils/parsers/rst/directives/body.py,
docutils/parsers/rst/directives/parts.py
@@ -24,6 +29,10 @@
auxiliary elements belonging to several categories (e.g. `nodes.Root`
and `nodes.BodyElements`) as parents of topics or sidebars.
+* docutils/writers/html/*
+
+ - New value "auto" for `initial_header_level`_ configuration setting.
+
* docutils/writers/html5_polyglot/responsive.css
- Increase indentation of enumerated lists to fit 2-digit numerals
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2025-12-02 19:48:48 UTC (rev 10269)
+++ trunk/docutils/docs/user/config.rst 2025-12-03 11:38:54 UTC (rev 10270)
@@ -1195,13 +1195,23 @@
initial_header_level
~~~~~~~~~~~~~~~~~~~~
-The initial level for section header elements. This does not affect the
-document title & subtitle; see doctitle_xform_.
+The level of the first *section* heading element
+(the `document title`_ always uses <h1>).
+Supported values:
+:1, ..., 6: <h1>, ..., <h6>,
+:auto: <h2> if there is a `document title`_, else <h1>. [#auto-header-level]_
+
+See also `doctitle_xform`_.
+
:Default: writer dependent
(see `[html4css1 writer]`_, `[html5 writer]`_, `[pep_html writer]`_).
:Option: ``--initial-header-level``.
+.. [#auto-header-level] Ensures the HTML document has a valid outline__
+ in documents with/without a document title.
+ New in Docutils 0.22.3.
+__ https://html.spec.whatwg.org/multipage/sections.html#outline
math_output
~~~~~~~~~~~
@@ -1489,14 +1499,8 @@
"minimal.css, plain.css".
:`xml_declaration <xml_declaration [html writers]_>`__: False.
-.. [#] Documents without (visible) document title may have <h2> as highest
- heading level, which is not recommended but valid (cf. "`Headings and
- outlines`__" in the HTML Standard). The default will change to None
- (<h2> if there is a document title, else <h1>) in Docutils 1.0.
+.. [#] The default will change to "auto" in Docutils 1.0.
-__ https://html.spec.whatwg.org/multipage/sections.html
- #headings-and-outlines-2
-
image_loading
"""""""""""""
Indicate at which point images should be loaded.
Modified: trunk/docutils/docutils/writers/_html_base.py
===================================================================
--- trunk/docutils/docutils/writers/_html_base.py 2025-12-02 19:48:48 UTC (rev 10269)
+++ trunk/docutils/docutils/writers/_html_base.py 2025-12-03 11:38:54 UTC (rev 10270)
@@ -85,7 +85,7 @@
'Does not affect document title & subtitle (see --no-doc-title).'
'(default: writer dependent).',
['--initial-header-level'],
- {'choices': '1 2 3 4 5 6'.split(), 'default': '2',
+ {'choices': '1 2 3 4 5 6 auto'.split(), 'default': '2',
'metavar': '<level>'}),
('Format for footnote references: one of "superscript" or '
'"brackets". (default: "brackets")',
@@ -295,7 +295,14 @@
settings = self.settings
self.language = languages.get_language(
settings.language_code, document.reporter)
- self.initial_header_level = int(settings.initial_header_level)
+ if settings.initial_header_level == 'auto':
+ if len(document) and document[0].next_node(
+ nodes.title, include_self=True, descend=False):
+ self.initial_header_level = 2
+ else:
+ self.initial_header_level = 1
+ else:
+ self.initial_header_level = int(settings.initial_header_level)
# image_loading (only defined for HTML5 writer)
_image_loading_default = 'link'
# convert legacy setting embed_images:
Modified: trunk/docutils/docutils/writers/html4css1/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html4css1/__init__.py 2025-12-02 19:48:48 UTC (rev 10269)
+++ trunk/docutils/docutils/writers/html4css1/__init__.py 2025-12-03 11:38:54 UTC (rev 10270)
@@ -68,7 +68,7 @@
'Specify the initial header level. Does not affect document '
'title & subtitle (see --no-doc-title). (default: 1 for "<h1>")',
['--initial-header-level'],
- {'choices': '1 2 3 4 5 6'.split(), 'default': '1',
+ {'choices': '1 2 3 4 5 6 auto'.split(), 'default': '1',
'metavar': '<level>'}),
math_output=(
'Math output format (one of "MathML", "HTML", "MathJax", or '
Modified: trunk/docutils/docutils/writers/html5_polyglot/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2025-12-02 19:48:48 UTC (rev 10269)
+++ trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2025-12-03 11:38:54 UTC (rev 10270)
@@ -73,7 +73,7 @@
'Specify the initial header level. Does not affect document '
'title & subtitle (see --no-doc-title). (default: 2 for "<h2>")',
['--initial-header-level'],
- {'choices': '1 2 3 4 5 6'.split(), 'default': '2',
+ {'choices': '1 2 3 4 5 6 auto'.split(), 'default': '2',
'metavar': '<level>'}),
no_xml_declaration=(
'Omit the XML declaration (default).',
Modified: trunk/docutils/test/test_writers/test_html5_polyglot_parts.py
===================================================================
--- trunk/docutils/test/test_writers/test_html5_polyglot_parts.py 2025-12-02 19:48:48 UTC (rev 10269)
+++ trunk/docutils/test/test_writers/test_html5_polyglot_parts.py 2025-12-03 11:38:54 UTC (rev 10270)
@@ -119,7 +119,8 @@
totest = {}
-totest['standard'] = ({}, [
+totest['standard'] = ({'initial_header_level': 'auto' # becomes standard in 1.0
+ }, [
['', # empty input string
{} # results in default parts
],
@@ -231,7 +232,8 @@
}],
])
-totest['no_title_promotion'] = ({'doctitle_xform': False}, [
+totest['no_title_promotion'] = ({'doctitle_xform': False,
+ 'initial_header_level': 'auto'}, [
["""\
+++++
Title
@@ -254,15 +256,15 @@
""",
{'fragment': """\
<section id="title">
-<h2>Title<a class="self-link" title="link to this section" href="#title"></a></h2>
+<h1>Title<a class="self-link" title="link to this section" href="#title"></a></h1>
<section id="not-a-subtitle">
-<h3>Not A Subtitle<a class="self-link" title="link to this section" href="#not-a-subtitle"></a></h3>
+<h2>Not A Subtitle<a class="self-link" title="link to this section" href="#not-a-subtitle"></a></h2>
<p>Some stuff</p>
<section id="section">
-<h4>Section<a class="self-link" title="link to this section" href="#section"></a></h4>
+<h3>Section<a class="self-link" title="link to this section" href="#section"></a></h3>
<p>Some more stuff</p>
<section id="another-section">
-<h5>Another Section<a class="self-link" title="link to this section" href="#another-section"></a></h5>
+<h4>Another Section<a class="self-link" title="link to this section" href="#another-section"></a></h4>
<p>And even more stuff</p>
</section>
</section>
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