Skip to content

Commit

Permalink
Fix problem with tests with Sphinx >= 7.3.0
Browse files Browse the repository at this point in the history
Sphinx 7.3.0 included a cosmetic change to param lists where if the
param has no description, it omits the " --". That's fine except
sphinx-js tests are very fragile in respects to the Sphinx output. This
includes Sphinx < 7.3.0 and Sphinx >= 7.3.0 expected output for relevant
tests.
  • Loading branch information
willkg committed Dec 23, 2024
1 parent 92305d3 commit 8bcefc8
Showing 1 changed file with 63 additions and 19 deletions.
82 changes: 63 additions & 19 deletions tests/test_build_js/test_build_js.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,14 @@
from sphinx import __version__ as sphinx_version
from tests.testing import SphinxBuildTestCase


SPHINX_VERSION = tuple(int(part) for part in sphinx_version.split('.'))

# NOTE(willkg): This is the version of Sphinx that removes trailing " --" from
# :params: lines when there is no description.
SPHINX_7_3_0 = (7, 3, 0)


class Tests(SphinxBuildTestCase):
"""Tests which require our big JS Sphinx tree to be built.
Expand Down Expand Up @@ -47,9 +55,22 @@ def test_autofunction_typedef(self):

def test_autofunction_callback(self):
"""Make sure @callback uses can be documented with autofunction."""
self._file_contents_eq(
'autofunction_callback',
u'requestCallback(responseCode)\n\n Some global callback\n\n Arguments:\n * **responseCode** (*number*) --\n')
if SPHINX_VERSION < SPHINX_7_3_0:
expected_content = (
'requestCallback(responseCode)\n\n'
' Some global callback\n\n'
' Arguments:\n'
' * **responseCode** (*number*) --\n'
)
else:
expected_content = (
'requestCallback(responseCode)\n\n'
' Some global callback\n\n'
' Arguments:\n'
' * **responseCode** (*number*)\n'
)

self._file_contents_eq('autofunction_callback', expected_content)

def test_autofunction_example(self):
"""Make sure @example tags can be documented with autofunction."""
Expand All @@ -64,25 +85,48 @@ def test_autofunction_example(self):
def test_autofunction_destructured_params(self):
"""Make sure that all documented params appears in the function
definition."""
self._file_contents_eq(
'autofunction_destructured_params',
u'destructuredParams(p1, p2)\n\n'
' Arguments:\n'
' * **p1** (*number*) --\n\n'
' * **p2** (*Object*) --\n\n'
' * **p2.foo** (*string*) --\n\n'
' * **p2.bar** (*string*) --\n')
if SPHINX_VERSION < SPHINX_7_3_0:
expected_content = (
'destructuredParams(p1, p2)\n\n'
' Arguments:\n'
' * **p1** (*number*) --\n\n'
' * **p2** (*Object*) --\n\n'
' * **p2.foo** (*string*) --\n\n'
' * **p2.bar** (*string*) --\n'
)
else:
expected_content = (
'destructuredParams(p1, p2)\n\n'
' Arguments:\n'
' * **p1** (*number*)\n\n'
' * **p2** (*Object*)\n\n'
' * **p2.foo** (*string*)\n\n'
' * **p2.bar** (*string*)\n'
)

self._file_contents_eq('autofunction_destructured_params', expected_content)

def test_autofunction_defaults_in_doclet(self):
"""Make sure param default values appear in the function definition,
when defined in JSDoc."""
self._file_contents_eq(
'autofunction_defaults_doclet',
'defaultsDocumentedInDoclet(func=() => 5, str="a string with \\" quote", strNum="42", strBool="true", num=5, nil=null)\n\n'
' Arguments:\n'
' * **func** (*function*) --\n\n'
' * **strNum** (*string*) --\n\n'
' * **strBool** (*string*) --\n')
if SPHINX_VERSION < SPHINX_7_3_0:
expected_content = (
'defaultsDocumentedInDoclet(func=() => 5, str="a string with \\" quote", strNum="42", strBool="true", num=5, nil=null)\n\n'
' Arguments:\n'
' * **func** (*function*) --\n\n'
' * **strNum** (*string*) --\n\n'
' * **strBool** (*string*) --\n'
)
else:
expected_content = (
'defaultsDocumentedInDoclet(func=() => 5, str="a string with \\" quote", strNum="42", strBool="true", num=5, nil=null)\n\n'
' Arguments:\n'
' * **func** (*function*)\n\n'
' * **strNum** (*string*)\n\n'
' * **strBool** (*string*)\n'
)

self._file_contents_eq('autofunction_defaults_doclet', expected_content)

def test_autofunction_defaults_in_code(self):
"""Make sure param default values appear in the function definition,
Expand Down Expand Up @@ -357,7 +401,7 @@ def test_union_types(self):
switched from " | " as the union separator back to "|".
"""
assert '* **fnodeA** (*Node|Fnode*) --' in self._file_contents('union')
assert '* **fnodeA** (*Node|Fnode*)' in self._file_contents('union')

def test_field_list_unwrapping(self):
"""Ensure the tails of field lists have line breaks and leading
Expand Down

0 comments on commit 8bcefc8

Please sign in to comment.