diff --git a/.coverage b/.coverage deleted file mode 100644 index 05a79683..00000000 Binary files a/.coverage and /dev/null differ diff --git a/requirements_dev.txt b/requirements_dev.txt index bf50d7ae..c4b471c4 100644 --- a/requirements_dev.txt +++ b/requirements_dev.txt @@ -5,3 +5,4 @@ nox pytest-cov recommonmark twine +defusedxml diff --git a/sphinx_js/ir.py b/sphinx_js/ir.py index e77d7eda..2aafb3d0 100644 --- a/sphinx_js/ir.py +++ b/sphinx_js/ir.py @@ -53,6 +53,11 @@ class TypeXRefExternal(TypeXRef): qualifiedName: str +@define +class DescriptionName: + text: str + + @define class DescriptionText: text: str @@ -63,7 +68,7 @@ class DescriptionCode: code: str -DescriptionItem = DescriptionText | DescriptionCode +DescriptionItem = DescriptionName | DescriptionText | DescriptionCode Description = str | Sequence[DescriptionItem] diff --git a/sphinx_js/renderers.py b/sphinx_js/renderers.py index b06cba70..ca398882 100644 --- a/sphinx_js/renderers.py +++ b/sphinx_js/renderers.py @@ -25,6 +25,7 @@ from .ir import ( Attribute, Class, + DescriptionName, DescriptionText, Exc, Function, @@ -127,6 +128,10 @@ def render_description(description: ir.Description) -> str: content = [] prev = "" for s in description: + if isinstance(s, DescriptionName): + prev = s.text + content.append(prev + "\n") + continue if isinstance(s, DescriptionText): prev = s.text content.append(prev) @@ -174,7 +179,7 @@ class Renderer: _add_span: bool _partial_path: list[str] _explicit_formal_params: str - _content: list[str] + _content: list[str] | StringList _options: dict[str, Any] def _parse_path(self, arg: str) -> None: @@ -192,7 +197,7 @@ def __init__( directive: Directive, app: Sphinx, arguments: list[str], - content: list[str] | None = None, + content: list[str] | StringList | None = None, options: dict[str, Any] | None = None, ): self._add_span = True diff --git a/sphinx_js/typedoc.py b/sphinx_js/typedoc.py index a4e877de..41fb1a1a 100644 --- a/sphinx_js/typedoc.py +++ b/sphinx_js/typedoc.py @@ -369,10 +369,12 @@ class Source(BaseModel): class DescriptionItem(BaseModel): - kind: Literal["text", "code"] + kind: Literal["name", "text", "code"] text: str def to_ir(self) -> ir.DescriptionItem: + if self.kind == "name": + return ir.DescriptionName(self.text) if self.kind == "text": return ir.DescriptionText(self.text) return ir.DescriptionCode(self.text) @@ -380,6 +382,7 @@ def to_ir(self) -> ir.DescriptionItem: class Tag(BaseModel): tag: str + name: str | None content: list[DescriptionItem] @@ -396,6 +399,8 @@ class Comment(BaseModel): def __init__(self, *args: Any, **kwargs: Any): super().__init__(*args, **kwargs) for tag in self.blockTags: + if tag.name: + tag.content.insert(0, DescriptionItem(kind="name", text=tag.name)) self.tags.setdefault(tag.tag.removeprefix("@"), []).append(tag.content) def get_description(self) -> Sequence[ir.DescriptionItem]: diff --git a/tests/test_build_js/test_build_js.py b/tests/test_build_js/test_build_js.py index 5d355d87..537f240d 100644 --- a/tests/test_build_js/test_build_js.py +++ b/tests/test_build_js/test_build_js.py @@ -50,7 +50,7 @@ def test_autofunction_callback(self): """Make sure @callback uses can be documented with autofunction.""" self._file_contents_eq( "autofunction_callback", - "requestCallback(responseCode)\n\n Some global callback\n\n Arguments:\n * **responseCode** (**number**) --\n", + "requestCallback(responseCode)\n\n Some global callback\n\n Arguments:\n * **responseCode** (**number**)\n", ) def test_autofunction_example(self): @@ -71,10 +71,10 @@ def test_autofunction_destructured_params(self): "autofunction_destructured_params", "destructuredParams(p1, p2)\n\n" " Arguments:\n" - " * **p1** (**number**) --\n\n" - " * **p2** (**Object**) --\n\n" - " * **p2.foo** (**string**) --\n\n" - " * **p2.bar** (**string**) --\n", + " * **p1** (**number**)\n\n" + " * **p2** (**Object**)\n\n" + " * **p2.foo** (**string**)\n\n" + " * **p2.bar** (**string**)\n", ) def test_autofunction_defaults_in_doclet(self): @@ -84,9 +84,9 @@ def test_autofunction_defaults_in_doclet(self): "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", + " * **func** (**function**)\n\n" + " * **strNum** (**string**)\n\n" + " * **strBool** (**string**)\n", ) def test_autofunction_defaults_in_code(self): @@ -377,7 +377,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 diff --git a/tests/test_build_ts/test_build_ts.py b/tests/test_build_ts/test_build_ts.py index bec679c2..a0f74b76 100644 --- a/tests/test_build_ts/test_build_ts.py +++ b/tests/test_build_ts/test_build_ts.py @@ -182,7 +182,7 @@ def test_predicate(self): predicate(c) Arguments: - * **c** (any) -- + * **c** (any) Returns: boolean (typeguard for "ConstructorlessClass()") @@ -273,9 +273,9 @@ def test_automodule(self): module.z(a, b) Arguments: - * **a** (number) -- + * **a** (number) - * **b** ({ a: string; b: number; }) -- + * **b** ({ a: string; b: number; }) Returns: number @@ -296,7 +296,7 @@ class module.A() A.g(a) Arguments: - * **a** (number) -- + * **a** (number) Returns: number @@ -306,9 +306,9 @@ class module.Z(a, b) *exported from* "module" Arguments: - * **a** (number) -- + * **a** (number) - * **b** (number) -- + * **b** (number) Z.x