Use container node for citation nodes to respect docutils spec. (#274)

Closes #273.

CHANGELOG.rst

@@ -1,6 +1,10 @@
 2.4.2 (in development)
 ----------------------
 
+* Use container node instead of paragraph node for containing bibliographies,
+  fixing a violation against the docutils spec
+  (see issue #273, reported by rappdw, with additional input from brechtm).
+
 2.4.1 (10 September 2021)
 -------------------------
 

src/sphinxcontrib/bibtex/domain.py

@@ -289,7 +289,7 @@ class BibtexDomain(Domain):
             encoding='',
             bibfiles={},
             data=pybtex.database.BibliographyData()),
-        bibliography_header=docutils.nodes.paragraph(),
+        bibliography_header=docutils.nodes.container(),
         bibliographies={},
         citations=[],
         citation_refs=[],
@@ -350,7 +350,7 @@ def __init__(self, env: "BuildEnvironment"):
         # parse bibliography header
         header = getattr(env.app.config, "bibtex_bibliography_header")
         if header:
-            self.data["bibliography_header"] = \
+            self.data["bibliography_header"] += \
                 parse_header(header, "bibliography_header")
 
     def clear_doc(self, docname: str) -> None:

src/sphinxcontrib/bibtex/foot_domain.py

@@ -35,7 +35,7 @@ class BibtexFootDomain(Domain):
     label = 'BibTeX Footnote Citations'
     data_version = 0
     initial_data = dict(
-        bibliography_header=docutils.nodes.paragraph(),
+        bibliography_header=docutils.nodes.container(),
     )
     reference_style: BaseReferenceStyle
 
@@ -60,7 +60,7 @@ def __init__(self, env: "BuildEnvironment"):
         # parse bibliography header
         header = getattr(env.app.config, "bibtex_footbibliography_header")
         if header:
-            self.data["bibliography_header"] = \
+            self.data["bibliography_header"] += \
                 parse_header(header, "foot_bibliography_header")
 
     def merge_domaindata(self, docnames: List[str], otherdata: Dict) -> None:

test/test_bibliography.py

@@ -233,10 +233,10 @@ def test_bibliography_custom_ids(app, warning) -> None:
     app.build()
     assert not warning.getvalue()
     output = (app.outdir / "index.html").read_text(encoding='utf-8')
-    assert '<p id="bibliography-id-1">' in output
-    assert '<p id="bibliography-id-2">' in output
-    assert '<p id="footbibliography-id-1">' in output
-    assert '<p id="footbibliography-id-2">' in output
+    assert ' id="bibliography-id-1"' in output
+    assert ' id="bibliography-id-2"' in output
+    assert ' id="footbibliography-id-1"' in output
+    assert ' id="footbibliography-id-2"' in output
     match1 = html_citations(text='.*Evensen.*').search(output)
     match2 = html_citations(text='.*Mandel.*').search(output)
     match3 = html_citations(text='.*Lorenc.*').search(output)

test/test_debug.py

@@ -24,7 +24,7 @@
             <reference internal="True" refid="id3" reftitle="The title.">
                 tes
             ]
-    <paragraph ids="id2">
+    <container ids="id2">
         <citation backrefs="id1" docname="index" ids="id3">
             <label support_smartquotes="False">
                 tes
@@ -89,7 +89,7 @@ def test_debug_minimal_example(app, warning) -> None:
         '                Nel87',
         '            ]',
         '        .',
-        '    <paragraph ids="id3">',
+        '    <container ids="id3">',
         '        <citation backrefs="id1 id2" docname="index" ids="id4">',
         '            <label support_smartquotes="False">',
         '                Nel87',