fix breaking tests

Author: chrisjsewell

AGENTS.md

@@ -85,7 +85,8 @@ tox -e py311-sphinx8
 # Run with coverage
 tox -- --cov=myst_parser
 
-# Update regression test fixtures
+# Update regression test fixtures (this will initially produce an error code if the files change)
+# but note, these files must pass for all python/sphinx/docutils versions
 tox -- --regen-file-failure --force-regen
 ```
 
@@ -337,5 +338,6 @@ flowchart TB
 - [markdown-it-py Documentation](https://markdown-it-py.readthedocs.io/)
 - [Docutils Repository](https://github.com/live-clones/docutils)
 - [Docutils Documentation](https://docutils.sourceforge.io/)
+- [Docutils release log](https://docutils.sourceforge.io/RELEASE-NOTES.html)
 - [Sphinx Repository](https://github.com/sphinx-doc/sphinx)
 - [Sphinx Extension Development](https://www.sphinx-doc.org/en/master/extdev/index.html)

myst_parser/mocking.py

@@ -454,12 +454,18 @@ def run(self) -> list[nodes.Element]:
             literal_block.line = 1  # TODO don;t think this should be 1?
             self.add_name(literal_block)
             if "number-lines" in self.options:
-                try:
-                    startline = int(self.options["number-lines"] or 1)
-                except ValueError as err:
-                    raise DirectiveError(
-                        3, ":number-lines: with non-integer start value"
-                    ) from err
+                # note starting in docutils 0.22 this option is now an integer instead of a string, see: https://github.com/live-clones/docutils/commit/f39ac1413e56a330c8fea6e0d080fed0ff2b8483
+                if self.options["number-lines"] is None:
+                    startline = 1
+                elif isinstance(self.options["number-lines"], int):
+                    startline = self.options["number-lines"]
+                else:
+                    try:
+                        startline = int(self.options["number-lines"] or 1)
+                    except ValueError as err:
+                        raise DirectiveError(
+                            3, ":number-lines: with non-integer start value"
+                        ) from err
                 endline = startline + len(file_content.splitlines())
                 file_content = file_content.removesuffix("\n")
                 tokens = NumberLines([([], file_content)], startline, endline)

tests/test_renderers/fixtures/docutil_link_resolution.md

@@ -128,14 +128,15 @@
         Test
     <subtitle ids="other test-1" names="other test">
         Other
-    <system_message backrefs="test-1" level="1" line="3" source="<src>/index.md" type="INFO">
-        <paragraph>
-            Duplicate implicit target name: "test".
     <target refid="test-1">
     <paragraph>
         <reference id_link="True" refid="test-1">
             <inline classes="std std-ref">
                 Other
+
+
+<src>/index.md:3: (INFO/1) Target name overrides implicit target name "test".
+<src>/index.md:3: (INFO/1) Hyperlink target "test-1" is not referenced.
 .
 
 [id-with-spaces] 

tests/test_renderers/fixtures/myst-config.txt

@@ -263,6 +263,12 @@ a
 <document source="<string>">
     <paragraph>
         a
+    <section classes="system-messages">
+        <title>
+            Docutils System Messages
+        <system_message level="2" source="<string>" type="WARNING">
+            <paragraph>
+                The `attrs_image` extension is deprecated, please use `attrs_inline` instead. [myst.deprecated]
 
 <string>:: (WARNING/2) The `attrs_image` extension is deprecated, please use `attrs_inline` instead. [myst.deprecated]
 .

tests/test_renderers/test_error_reporting.py

@@ -20,4 +20,9 @@ def test_basic(file_params):
         parser=Parser(),
         settings_overrides={"warning_stream": report_stream},
     )
-    file_params.assert_expected(report_stream.getvalue(), rstrip=True)
+    text = report_stream.getvalue()
+    # changed in docutils 0.23
+    text = text.replace(
+        "corresponding footnote available", "corresponding footnotes available"
+    )
+    file_params.assert_expected(text, rstrip=True)

tests/test_renderers/test_fixtures_docutils.py

@@ -12,6 +12,7 @@
 
 import pytest
 from conftest import normalize_doctree_xml
+from docutils import __version_info__ as docutils_version
 from docutils.core import Publisher, publish_doctree
 from pytest_param_files import ParamTestData
 
@@ -51,6 +52,11 @@ def test_link_resolution(file_params: ParamTestData):
     settings = settings_from_cmdline(file_params.description)
     report_stream = StringIO()
     settings["warning_stream"] = report_stream
+    if file_params.title == "explicit>implicit":
+        if docutils_version < (0, 22):
+            # reporting changed in docutils 0.22
+            pytest.skip("different in docutils>=0.22")
+        settings["report_level"] = 0
     doctree = publish_doctree(
         file_params.content,
         source_path="<src>/index.md",

tests/test_renderers/test_myst_config.py

@@ -6,6 +6,7 @@
 
 import pytest
 from conftest import normalize_doctree_xml
+from docutils import __version_info__ as docutils_version
 from docutils.core import Publisher, publish_string
 from pytest_param_files import ParamTestData
 
@@ -18,6 +19,9 @@
 @pytest.mark.param_file(FIXTURE_PATH / "myst-config.txt")
 def test_cmdline(file_params: ParamTestData):
     """The description is parsed as a docutils commandline"""
+    if file_params.title == "attrs_image" and docutils_version < (0, 22):
+        # loose system messages are also output to ast in 0.22 https://github.com/live-clones/docutils/commit/dc4e16315b4fbe391417a6f7aad215b9389a9c74
+        pytest.skip("different in docutils>=0.22")
     pub = Publisher(parser=Parser())
     try:
         pub.process_command_line(shlex.split(file_params.description or ""))

tests/test_sphinx/sourcedirs/includes/index.md

@@ -14,7 +14,7 @@
 
 ```{include} include_code.py
 :code: python
-:number-lines: 0
+:number-lines: 1
 ```
 
 ```{include} include_literal.txt

tests/test_sphinx/test_sphinx_builds/test_includes.html

@@ -115,8 +115,8 @@ <h2>
 </pre>
       </div>
      </div>
-     <pre class="code python literal-block"><small class="ln">0 </small><code data-lineno="0 "><span class="keyword">def</span><span class="whitespace"> </span><span class="name function">a_func</span><span class="punctuation">(</span><span class="name">param</span><span class="punctuation">):</span><span class="whitespace">
-</span></code><small class="ln">1 </small><code data-lineno="1 "><span class="whitespace"></span>    <span class="name builtin">print</span><span class="punctuation">(</span><span class="name">param</span><span class="punctuation">)</span></code></pre>
+     <pre class="code python literal-block"><small class="ln">1 </small><code data-lineno="1 "><span class="keyword">def</span><span class="whitespace"> </span><span class="name function">a_func</span><span class="punctuation">(</span><span class="name">param</span><span class="punctuation">):</span><span class="whitespace">
+</span></code><small class="ln">2 </small><code data-lineno="2 "><span class="whitespace"></span>    <span class="name builtin">print</span><span class="punctuation">(</span><span class="name">param</span><span class="punctuation">)</span></code></pre>
      <div class="highlight-default notranslate">
       <div class="highlight">
        <pre><span></span><span class="n">This</span> <span class="n">should</span> <span class="n">be</span> <span class="o">*</span><span class="n">literal</span><span class="o">*</span>

tests/test_sphinx/test_sphinx_builds/test_includes.xml

@@ -76,7 +76,7 @@
                     )
             <literal_block classes="code python" source="include_code.py" xml:space="preserve">
                 <inline classes="ln">
-                    0
+                    1
                 <inline classes="keyword">
                     def
                 <inline classes="whitespace">
@@ -92,7 +92,7 @@
                 <inline classes="whitespace">
 
                 <inline classes="ln">
-                    1
+                    2
                 <inline classes="whitespace">
 
                 <inline classes="name builtin">