Skip to content

sphinx 5 compatibility #399

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
drammock opened this issue May 25, 2022 · 4 comments · Fixed by #403
Closed

sphinx 5 compatibility #399

drammock opened this issue May 25, 2022 · 4 comments · Fixed by #403

Comments

@drammock
Copy link
Contributor

drammock commented May 25, 2022 •
edited
Loading

In one of MNE-Python's CIs we're using sphinx 5.0 beta, and seeing this deprecation warning percolating up from docutils 0.18.x:

Traceback (most recent call last):
  File "/home/circleci/python_env/lib/python3.8/site-packages/sphinx/events.py", line 94, in emit
    results.append(listener.handler(self.app, *args))
  File "/home/circleci/python_env/lib/python3.8/site-packages/numpydoc/numpydoc.py", line 104, in relabel_references
    for citation_node in doc.traverse(citation):
  File "/home/circleci/python_env/lib/python3.8/site-packages/docutils/nodes.py", line 240, in traverse
    warnings.warn('nodes.Node.traverse() is obsoleted by Node.findall().',
PendingDeprecationWarning: nodes.Node.traverse() is obsoleted by Node.findall().

I can probably take a swing at this in the next week or so (?) but would be happy if someone else picked it up too

here's the API ref for findall: https://pydoc.dev/docutils/latest/docutils.nodes.Node.html#findall
@drammock drammock mentioned this issue May 25, 2022
Merged
@jarrodmillman
Copy link
Member

Do you propose dropping support for docutils < 0.18.1?

@drammock
Copy link
Contributor Author

Do you propose dropping support for docutils < 0.18.1?

My first thought was to do a try/except block importing those specific node methods

@jarrodmillman
Copy link
Member

We are getting the following failures with docutils == 0.18.1 in #402:

=================================== FAILURES ===================================
_________________________ test_reference[html_file0-1] _________________________

sphinx_app = <sphinx.application.Sphinx object at 0x7f9274a6a5b0>
html_file = ['index.html'], expected_length = 1

    @pytest.mark.parametrize(
        ("html_file", "expected_length"),
        (
            (["index.html"], 1),
            (["generated", "numpydoc_test_module.my_function.html"], 1),
            (["generated", "numpydoc_test_module.MyClass.html"], 1),
        ),
    )
    def test_reference(sphinx_app, html_file, expected_length):
        """Test for bad references"""
        out_dir = sphinx_app.outdir
    
        with open(op.join(out_dir, *html_file)) as fid:
            html = fid.read()
    
        reference_list = re.findall(r'<a class="fn-backref" href="\#id\d+">(.*)<\/a>', html)
    
>       assert len(reference_list) == expected_length
E       assert 0 == 1
E        +  where 0 = len([])

expected_length = 1
fid        = <_io.TextIOWrapper name='/tmp/pytest-of-runner/pytest-0/root/_build/html/index.html' mode='r' encoding='UTF-8'>
html       = '\n<!DOCTYPE html>\n\n<html lang="en">\n  <head>\n    <meta charset="utf-8" />\n    <meta name="viewport" content="wid...ref="_sources/index.rst.txt"\n          rel="nofollow">Page source</a>\n    </div>\n\n    \n\n    \n  </body>\n</html>'
html_file  = ['index.html']
out_dir    = '/tmp/pytest-of-runner/pytest-0/root/_build/html'
reference_list = []
sphinx_app = <sphinx.application.Sphinx object at 0x7f9274a6a5b0>

numpydoc/tests/test_full.py:94: AssertionError
_________________________ test_reference[html_file1-1] _________________________

sphinx_app = <sphinx.application.Sphinx object at 0x7f9274a6a5b0>
html_file = ['generated', 'numpydoc_test_module.my_function.html']
expected_length = 1

    @pytest.mark.parametrize(
        ("html_file", "expected_length"),
        (
            (["index.html"], 1),
            (["generated", "numpydoc_test_module.my_function.html"], 1),
            (["generated", "numpydoc_test_module.MyClass.html"], 1),
        ),
    )
    def test_reference(sphinx_app, html_file, expected_length):
        """Test for bad references"""
        out_dir = sphinx_app.outdir
    
        with open(op.join(out_dir, *html_file)) as fid:
            html = fid.read()
    
        reference_list = re.findall(r'<a class="fn-backref" href="\#id\d+">(.*)<\/a>', html)
    
>       assert len(reference_list) == expected_length
E       assert 0 == 1
E        +  where 0 = len([])

expected_length = 1
fid        = <_io.TextIOWrapper name='/tmp/pytest-of-runner/pytest-0/root/_build/html/generated/numpydoc_test_module.my_function.html' mode='r' encoding='UTF-8'>
html       = '\n<!DOCTYPE html>\n\n<html lang="en">\n  <head>\n    <meta charset="utf-8" />\n    <meta name="viewport" content="wid..._module.my_function.rst.txt"\n          rel="nofollow">Page source</a>\n    </div>\n\n    \n\n    \n  </body>\n</html>'
html_file  = ['generated', 'numpydoc_test_module.my_function.html']
out_dir    = '/tmp/pytest-of-runner/pytest-0/root/_build/html'
reference_list = []
sphinx_app = <sphinx.application.Sphinx object at 0x7f9274a6a5b0>

numpydoc/tests/test_full.py:94: AssertionError
_________________________ test_reference[html_file2-1] _________________________

sphinx_app = <sphinx.application.Sphinx object at 0x7f9274a6a5b0>
html_file = ['generated', 'numpydoc_test_module.MyClass.html']
expected_length = 1

    @pytest.mark.parametrize(
        ("html_file", "expected_length"),
        (
            (["index.html"], 1),
            (["generated", "numpydoc_test_module.my_function.html"], 1),
            (["generated", "numpydoc_test_module.MyClass.html"], 1),
        ),
    )
    def test_reference(sphinx_app, html_file, expected_length):
        """Test for bad references"""
        out_dir = sphinx_app.outdir
    
        with open(op.join(out_dir, *html_file)) as fid:
            html = fid.read()
    
        reference_list = re.findall(r'<a class="fn-backref" href="\#id\d+">(.*)<\/a>', html)
    
>       assert len(reference_list) == expected_length
E       assert 0 == 1
E        +  where 0 = len([])

expected_length = 1
fid        = <_io.TextIOWrapper name='/tmp/pytest-of-runner/pytest-0/root/_build/html/generated/numpydoc_test_module.MyClass.html' mode='r' encoding='UTF-8'>
html       = '\n<!DOCTYPE html>\n\n<html lang="en">\n  <head>\n    <meta charset="utf-8" />\n    <meta name="viewport" content="wid...test_module.MyClass.rst.txt"\n          rel="nofollow">Page source</a>\n    </div>\n\n    \n\n    \n  </body>\n</html>'
html_file  = ['generated', 'numpydoc_test_module.MyClass.html']
out_dir    = '/tmp/pytest-of-runner/pytest-0/root/_build/html'
reference_list = []
sphinx_app = <sphinx.application.Sphinx object at 0x7f9274a6a5b0>

numpydoc/tests/test_full.py:94: AssertionError
=============================== warnings summary ===============================
numpydoc/tests/test_full.py::test_MyClass
numpydoc/tests/test_full.py::test_MyClass
numpydoc/tests/test_full.py::test_MyClass
  /home/runner/work/numpydoc/numpydoc/numpydoc/numpydoc.py:104: PendingDeprecationWarning: nodes.Node.traverse() is obsoleted by Node.findall().
    for citation_node in doc.traverse(citation):

numpydoc/tests/test_full.py::test_MyClass
numpydoc/tests/test_full.py::test_MyClass
numpydoc/tests/test_full.py::test_MyClass
  /home/runner/work/numpydoc/numpydoc/numpydoc/numpydoc.py:84: PendingDeprecationWarning: nodes.Node.traverse() is obsoleted by Node.findall().
    section_node.traverse(

numpydoc/tests/test_full.py::test_MyClass
numpydoc/tests/test_full.py::test_MyClass
numpydoc/tests/test_full.py::test_MyClass
numpydoc/tests/test_full.py::test_MyClass
numpydoc/tests/test_full.py::test_MyClass
  /home/runner/work/numpydoc/numpydoc/numpydoc/numpydoc.py:124: PendingDeprecationWarning: nodes.Node.traverse() is obsoleted by Node.findall().
    for xref_node in ref.parent.traverse(matching_pending_xref):

numpydoc/tests/test_full.py::test_MyClass
numpydoc/tests/test_full.py::test_MyClass
numpydoc/tests/test_full.py::test_MyClass
  /home/runner/work/numpydoc/numpydoc/numpydoc/numpydoc.py:132: PendingDeprecationWarning: nodes.Node.traverse() is obsoleted by Node.findall().
    for ref in doc.traverse(reference, descend=True):

numpydoc/tests/test_full.py::test_MyClass
numpydoc/tests/test_full.py::test_MyClass
numpydoc/tests/test_full.py::test_MyClass
  /home/runner/work/numpydoc/numpydoc/numpydoc/numpydoc.py:135: PendingDeprecationWarning: nodes.Node.traverse() is obsoleted by Node.findall().
    for citation_node in doc.traverse(citation, descend=True):

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
-- generated xml file: /home/runner/work/numpydoc/numpydoc/junit-results.xml ---


=========================== short test summary info ============================
XFAIL numpydoc/tests/test_validate.py::TestValidator::test_bad_docstrings[BadParameters-blank_lines-msgs30]
XFAIL numpydoc/tests/test_validate.py::TestValidator::test_bad_docstrings[BadReturns-no_type-msgs33]
FAILED numpydoc/tests/test_full.py::test_reference[html_file0-1] - assert 0 == 1
FAILED numpydoc/tests/test_full.py::test_reference[html_file1-1] - assert 0 == 1
FAILED numpydoc/tests/test_full.py::test_reference[html_file2-1] - assert 0 == 1
============ 3 failed, 234 passed, 2 xfailed, 17 warnings in 4.27s =============
Error: Process completed with exit code 1.

@drammock drammock mentioned this issue May 28, 2022
Merged
@drammock
Copy link
Contributor Author

@jarrodmillman I've fixed the warnings and the FAILs in #403, but I can't wrap my head around the gigantic pytest.mark.parametrize in test_bad_docstrings so I wasn't able to fix the XFAILs. Can you or one of the other devs take a look (and maybe push a commit to #403)?

@hmaarrfk hmaarrfk mentioned this issue Sep 25, 2023
Closed
5 tasks
@lukasjuhrich lukasjuhrich mentioned this issue Jan 25, 2024
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Use node.findall if available (docutils 18.x) drammock/numpydoc
2 participants
@jarrodmillman @drammock