From dd74bd70d76e1cebf6be7ae84f69380b423fee25 Mon Sep 17 00:00:00 2001
From: Hassan Kibirige <has2k1@gmail.com>
Date: Wed, 16 Aug 2023 22:38:05 +0300
Subject: [PATCH] DOC: Use definition lists for docstring parameters

---
 .gitignore        |  1 +
 qdoc/_quarto.yml  | 50 ++++++++++++++---------------
 qdoc/_renderer.py | 82 +++++++++++++++++++++++++++++++++++++++--------
 3 files changed, 95 insertions(+), 38 deletions(-)

diff --git a/.gitignore b/.gitignore
index 03830ea12..27a321674 100644
--- a/.gitignore
+++ b/.gitignore
@@ -95,6 +95,7 @@ plotnine/_version.py
 qdoc/plotnine_examples/
 qdoc/reference/
 qdoc/_site/
+qdoc/_inv/
 qdoc/.quarto/
 qdoc/gallery/thumbnails
 qdoc/objects.json
diff --git a/qdoc/_quarto.yml b/qdoc/_quarto.yml
index a7282e02b..b0c02b707 100644
--- a/qdoc/_quarto.yml
+++ b/qdoc/_quarto.yml
@@ -12,32 +12,31 @@ project:
 filters:
   - interlinks
 
+# interlinks are slow
 interlinks:
-  sources: {}
-  # interlinks are slow
-  # sources:
-  #   python:
-  #     url: https://docs.python.org/3/
-  #   matplotlib:
-  #     url: https://matplotlib.org/stable/
-  #   mizani:
-  #     url: https://mizani.readthedocs.io/stable/
-  #   numpy:
-  #     url: https://numpy.org/doc/stable/
-  #   scipy:
-  #     url: https://docs.scipy.org/doc/scipy/
-  #   statsmodels:
-  #     url: https://www.statsmodels.org/stable/
-  #   pandas:
-  #     url: https://pandas.pydata.org/pandas-docs/stable/
-  #   sklearn:
-  #     url: https://scikit-learn.org/stable/
-  #   skmisc:
-  #     url: https://has2k1.github.io/scikit-misc/stable/
-  #   adjustText:
-  #     url: https://adjusttext.readthedocs.io/en/latest/
-  #   patsy:
-  #      url: https://patsy.readthedocs.io/en/stable/
+  sources:
+    python:
+      url: https://docs.python.org/3/
+#   matplotlib:
+#     url: https://matplotlib.org/stable/
+#   mizani:
+#     url: https://mizani.readthedocs.io/stable/
+#   numpy:
+#     url: https://numpy.org/doc/stable/
+#   scipy:
+#     url: https://docs.scipy.org/doc/scipy/
+#   statsmodels:
+#     url: https://www.statsmodels.org/stable/
+#   pandas:
+#     url: https://pandas.pydata.org/pandas-docs/stable/
+#   sklearn:
+#     url: https://scikit-learn.org/stable/
+#   skmisc:
+#     url: https://has2k1.github.io/scikit-misc/stable/
+#   adjustText:
+#     url: https://adjusttext.readthedocs.io/en/latest/
+#   patsy:
+#      url: https://patsy.readthedocs.io/en/stable/
 
 website:
   title: "plotnine {{< env VERSION >}}"
@@ -57,6 +56,7 @@ format:
   html:
     toc: true
     css: styles.css
+from: markdown+definition_lists
 
 quartodoc:
   style: pkgdown
diff --git a/qdoc/_renderer.py b/qdoc/_renderer.py
index 363456412..7c747f1ff 100644
--- a/qdoc/_renderer.py
+++ b/qdoc/_renderer.py
@@ -3,8 +3,11 @@
 import html
 import typing
 from pathlib import Path
+from textwrap import indent
 
 from griffe import dataclasses as dc
+from griffe import expressions as expr
+from griffe.docstrings import dataclasses as ds
 from numpydoc.docscrape import NumpyDocString
 from plum import dispatch
 from quartodoc import MdRenderer
@@ -25,17 +28,19 @@
 {examples}
 """
 
+INDENT = " " * 4
+PARAM_TPL = """\
+<code class="python">{name}{annotation}{default}</code>
 
-class Renderer(MdRenderer):
-    style = "plotnine"
+:{indented_description}
+"""
 
-    def _render_table(self, rows, headers):
-        colalign = [""] * len(headers)
-        table = tabulate(
-            rows, headers=headers, tablefmt="unsafehtml", colalign=colalign
-        )
+# NOTE: https://github.com/mkdocstrings/griffe/pull/194
+# will break this module.
 
-        return table.replace("<table", '<table class="table" ')
+
+class Renderer(MdRenderer):
+    style = "plotnine"
 
     @dispatch
     def render(self, el: DocClass):  # type: ignore
@@ -56,7 +61,9 @@ def render(self, el: dc.Object | dc.Alias):  # type: ignore # noqa: F811
         return converted
 
     @dispatch
-    def render(self, el: qast.DocstringSectionSeeAlso):  # noqa: F811
+    def render(  # type: ignore
+        self, el: qast.DocstringSectionSeeAlso  # noqa: F811
+    ):
         lines = el.value.split("\n")
 
         # each entry in result has form:
@@ -77,10 +84,29 @@ def render(self, el: qast.DocstringSectionSeeAlso):  # noqa: F811
 
         return "* " + "\n* ".join(result)
 
-    def render_annotation(
-        self, el: dc.Name | dc.Expression | None  # type: ignore
-    ):
-        return super().render_annotation(el)
+    @dispatch
+    def render_annotation(self, el: None):  # type: ignore
+        return ""
+
+    @dispatch
+    def render_annotation(self, el: expr.Expression):  # type: ignore
+        # an expression is essentially a list[expr.Name | str]
+        # e.g. Optional[TagList]
+        #   -> [Name(source="Optional", ...), "[", Name(...), "]"]
+
+        return "".join([self.render_annotation(a) for a in el])
+
+    @dispatch
+    def render_annotation(self, el: expr.Name):  # type: ignore
+        # e.g. Name(source="Optional", full="typing.Optional")
+        return f"[{el.source}](`{el.full}`)"
+
+    @dispatch
+    def render_annotation(self, el: str):
+        """
+        Override base class so that no escaping is done
+        """
+        return el
 
     @dispatch
     def summarize(self, el: dc.Object | dc.Alias):
@@ -96,3 +122,33 @@ def signature(self, el: dc.Object | dc.Alias):
         if skip:
             return ""
         return super().signature(el)  # type: ignore
+
+    # parameters ----
+    @dispatch
+    def render(self, el: ds.DocstringParameter) -> str:  # type: ignore # noqa: F811
+        """
+        Return parameter docstring as a definition term & description
+
+        output-format: quarto/pandoc
+        """
+        annotation = self.render_annotation(el.annotation)  # type: ignore
+        kwargs = {
+            "name": el.name,
+            "annotation": f": {annotation}" if annotation else "",
+            "default": f" = {el.default}" if el.default else "",
+            "indented_description": indent(el.description, INDENT),
+        }
+        return PARAM_TPL.format(**kwargs)
+
+    @dispatch
+    def render(self, el: ds.DocstringSectionParameters) -> str:
+        """
+        Return parameters docstring as a definition list
+
+        output-format: quarto/pandoc
+        """
+        definitions = [
+            self.render(ds_parameter)  # type: ignore
+            for ds_parameter in el.value
+        ]
+        return "\n".join(definitions)