Add support for deprecated tag (#63)

pyodide · Sep 25, 2023 · dae27f1 · dae27f1
1 parent e99a7de
commit dae27f1
Show file tree

Hide file tree

Showing 5 changed files with 42 additions and 7 deletions.
diff --git a/sphinx_js/renderers.py b/sphinx_js/renderers.py
@@ -381,13 +381,16 @@ class AutoFunctionRenderer(JsRenderer):
     _renderer_type = "function"
 
     def _template_vars(self, name: str, obj: Function) -> dict[str, Any]:  # type: ignore[override]
+        deprecated = obj.deprecated
+        if not isinstance(deprecated, bool):
+            deprecated = self.render_description(deprecated)
         return dict(
             name=name,
             params=self._formal_params(obj),
             fields=self._fields(obj),
             description=self.render_description(obj.description),
             examples=obj.examples,
-            deprecated=obj.deprecated,
+            deprecated=deprecated,
             is_optional=obj.is_optional,
             is_static=obj.is_static,
             see_also=obj.see_alsos,

diff --git a/sphinx_js/typedoc.py b/sphinx_js/typedoc.py
@@ -311,8 +311,15 @@ def __init__(self, *args: Any, **kwargs: Any):
     def get_description(self) -> Sequence[ir.DescriptionItem]:
         return description_to_ir(self.summary)
 
-    def get_returns(self) -> Sequence[ir.DescriptionItem]:
-        return description_to_ir(next(iter(self.tags["returns"]), []))
+    def get_tag_list(self, tag: str) -> list[Sequence[ir.DescriptionItem]]:
+        return [description_to_ir(t) for t in self.tags[tag]]
+
+    def get_tag_one(self, tag: str) -> Sequence[ir.DescriptionItem]:
+        l = self.tags[tag]
+        if not l:
+            return []
+        assert len(l) == 1
+        return description_to_ir(l[0])
 
 
 class Flags(BaseModel):
@@ -368,7 +375,7 @@ class TopLevelPropertiesDict(TypedDict):
     deppath: str | None
     description: Sequence[ir.DescriptionItem]
     line: int | None
-    deprecated: bool
+    deprecated: Sequence[ir.DescriptionItem] | bool
     examples: list[str]
     see_alsos: list[str]
     properties: list[ir.Attribute]
@@ -385,6 +392,8 @@ def short_name(self) -> str:
         return self.name
 
     def _top_level_properties(self) -> TopLevelPropertiesDict:
+        deprecated: Sequence[ir.DescriptionItem] | bool
+        deprecated = self.comment.get_tag_one("deprecated") or False
         return dict(
             name=self.short_name(),
             path=ir.Pathname(self.path),
@@ -393,7 +402,7 @@ def _top_level_properties(self) -> TopLevelPropertiesDict:
             description=self.comment.get_description(),
             line=self.sources[0].line if self.sources else None,
             # These properties aren't supported by TypeDoc:
-            deprecated=False,
+            deprecated=deprecated,
             examples=[],
             see_alsos=[],
             properties=[],
@@ -775,7 +784,7 @@ def return_type(self, converter: Converter) -> list[ir.Return]:
         return [
             ir.Return(
                 type=self.type.render_name(converter),
-                description=self.comment.get_returns(),
+                description=self.comment.get_tag_one("returns"),
             )
         ]
 

diff --git a/tests/test_build_ts/source/class.ts b/tests/test_build_ts/source/class.ts
@@ -71,4 +71,10 @@ export function thunk(b : typeof blah) {
  * A problematic self referential function
  * @param b troublemaker
  */
-export function quik(b: typeof quik)  {}
+export function selfReferential(b: typeof selfReferential)  {}
+
+
+/**
+ * @deprecated since v20!
+ */
+export function deprecatedFunction() {}
diff --git a/tests/test_build_ts/source/docs/deprecated.rst b/tests/test_build_ts/source/docs/deprecated.rst
@@ -0,0 +1 @@
+.. js:autofunction:: deprecatedFunction
diff --git a/tests/test_build_ts/test_build_ts.py b/tests/test_build_ts/test_build_ts.py
@@ -1,3 +1,5 @@
+from textwrap import dedent
+
 from bs4 import BeautifulSoup
 from conftest import TYPEDOC_VERSION
 
@@ -104,6 +106,20 @@ def test_optional_members(self):
             "   OptionalThings.foop?()\n",
         )
 
+    def test_deprecated(self):
+        self._file_contents_eq(
+            "deprecated",
+            dedent(
+                """\
+                deprecatedFunction()
+
+                   Note:
+
+                     Deprecated: since v20!
+                """
+            ),
+        )
+
 
 class HtmlBuilderTests(SphinxBuildTestCase):
     """Tests which require an HTML build of our Sphinx tree, for checking