Fix CI

requirements_dev.txt

@@ -5,3 +5,4 @@ nox
 pytest-cov
 recommonmark
 twine
+defusedxml

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]
 

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
@@ -522,6 +527,8 @@ def _template_vars(self, name: str, obj: Function) -> dict[str, Any]:  # type: i
         deprecated = obj.deprecated
         if not isinstance(deprecated, bool):
             deprecated = render_description(deprecated)
+        if obj.examples:
+            print("obj.examples:", obj.examples)
         return dict(
             name=name,
             params=self._formal_params(obj),

sphinx_js/typedoc.py

@@ -369,17 +369,20 @@ 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)
 
 
 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]:
@@ -500,6 +505,8 @@ def _top_level_properties(self) -> TopLevelPropertiesDict:
         deprecated = self.comment.get_tag_one("deprecated")
         if not deprecated:
             deprecated = "deprecated" in self.comment.tags
+        if self.comment.get_tag_list("example"):
+            print(self.comment)
         return dict(
             name=self.short_name(),
             path=ir.Pathname(self.path),

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

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