Exclude docutils 0.18 and 0.19 as they may generate invalid html (#330)

* Circumvent docutils bug

* Update footnote regexp for docutils 0.20.

* Use older docutils and jinja2 to test against Python 3.7.

* Pass matrix options to pip install . to ensure dependencies are respected.

* Bump minor version (since reqs are changing).

* Remove python 3.6 from testing as EOL.

* Stop testing against Sphinx 2.1.

---------

Co-authored-by: Matthias C. M. Troffaes <matthias.troffaes@gmail.com>

.github/workflows/python-package.yml

@@ -13,26 +13,26 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.6', '3.7', '3.8', '3.9', '3.10', '3.11-dev']
+        python-version: ['3.8', '3.9', '3.10', '3.11']
         pip-sphinx: ['sphinx']
         pytest-options: ['']
         include:
+          # python 3.7 (needs older docutils and jinja2)
+          - python-version: '3.7'
+            pip-sphinx: '"docutils<0.18" "jinja2<3.1"'
+            pytest-options: ''
           # numpydoc tests
-          - python-version: '3.10'
+          - python-version: '3.11'
             pip-sphinx: 'sphinx numpydoc'
             pytest-options: '-m "numpydoc"'
           # rinohtype tests
-          - python-version: '3.10'
+          - python-version: '3.11'
             pip-sphinx: 'sphinx https://github.com/brechtm/rinohtype/archive/refs/heads/master.zip'
             pytest-options: '-m "rinohtype"'
           # cython tests
-          - python-version: '3.10'
+          - python-version: '3.11'
             pip-sphinx: 'sphinx test/some_cython_module'
             pytest-options: '-m "cython"'
-          # sphinx 2.1 (the oldest supported version, released for Python 3.7)
-          - python-version: '3.7'
-            pip-sphinx: '"sphinx==2.1" "docutils==0.16" "jinja2<3.1"'
-            pytest-options: ''
           # latest of sphinx 3.x series (released for Python 3.9)
           - python-version: '3.9'
             pip-sphinx: '"sphinx<4" "jinja2<3.1"'
@@ -42,7 +42,7 @@ jobs:
             pip-sphinx: '"sphinx<5"'
             pytest-options: ''
           # sphinx pre-release
-          - python-version: '3.10'
+          - python-version: '3.11'
             pip-sphinx: '--pre sphinx'
             pytest-options: ''
     steps:
@@ -55,8 +55,7 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         python -m pip install pytest codecov coverage
-        python -m pip install ${{ matrix.pip-sphinx }}
-        pip install .
+        python -m pip install . ${{ matrix.pip-sphinx }}
     - name: Install extra dependencies
       run: |
         python -m pip install flake8 check-manifest mypy types-setuptools types-docutils

CHANGELOG.rst

@@ -1,12 +1,19 @@
-2.5.1 (in development)
+2.6.0 (in development)
 ----------------------
 
+* Exclude docutils 0.18 and 0.19 to fix generation of a spurious div tag in the
+  html builder (see issues #330, #329, #323, #322, #309).
+
 * Add test for running the extension on Cython modules (see issue #308).
 
 * Running pytest without arguments will now by default skip all marked tests
   that require additional dependencies (currently numpydoc, rinohtype, and
   cython).
 
+* Python 3.6 is EOL and is therefore no longer officially supported.
+
+* Sphinx versions 2.x (and lower) are no longer supported.
+
 2.5.0 (22 August 2022)
 ----------------------
 

requirements.txt

@@ -1,5 +1,5 @@
 Sphinx>=2.1
-docutils>=0.8
+docutils>=0.8,!=1.18.*,!=1.19.*
 pybtex>=0.24
 pybtex-docutils>=1.0.0
 dataclasses; python_version < '3.7'

src/sphinxcontrib/bibtex/__init__.py

@@ -51,7 +51,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_role("footcite", FootCiteRole())
 
     return {
-        'version': '2.5.1a0',
+        'version': '2.6.0a0',
         'env_version': 9,
         'parallel_read_safe': True,
         'parallel_write_safe': True,

test/common.py

@@ -132,9 +132,11 @@ def html_footnotes(id_=RE_ID, text=RE_TEXT):
             r'<dd><p>(?P<text>{text})</p>\n</dd>'.format(
                 id_=id_, backref_id=RE_ID, label=RE_NUM, text=text))
     else:
+        foot_role = 'role='"note"'' if docutils.__version_info__ < (0, 20) \
+            else 'role="doc-footnote"'
         return re.compile(
             r'<aside class="footnote brackets" id="(?P<id_>{id_})"'
-            r' role="note">\s*'
+            r' {foot_role}>\s*'
             r'<span class="label">'
             r'<span class="fn-bracket">\[</span>'
             r'(?:<a {back_role} href="#(?P<backref>{backref_id})">)?'
@@ -151,7 +153,7 @@ def html_footnotes(id_=RE_ID, text=RE_TEXT):
             r'<p>(?P<text>{text})</p>\s*'
             r'</aside>'
             .format(
-                back_role='role="doc-backlink"',
+                foot_role=foot_role, back_role='role="doc-backlink"',
                 id_=id_, label=RE_NUM, text=text, backref_id=RE_ID))