Improvements to documentation

guide/webapp/display/markdown.py

@@ -17,6 +17,7 @@ from .plugins.hook import Hook
 from .plugins.mermaid import Mermaid
 from .plugins.notification import Notification
 from .plugins.span import span
+from .plugins.inline_directive import inline_directive
 from .plugins.tabs import Tabs
 from .text import slugify
 
@@ -55,10 +56,12 @@ class DocsRenderer(HTMLRenderer):
         )
 
     def link(self, text: str, url: str, title: str | None = None) -> str:
-        url = self.safe_url(url).removesuffix(".md")
-        if not url.endswith("/"):
+        url = self.safe_url(url).replace(".md", ".html")
+        url, anchor = url.split("#", 1) if "#" in url else (url, None)
+        if not url.endswith("/") and not url.endswith(".html"):
             url += ".html"
-
+        if anchor:
+            url += f"#{anchor}"
         attributes: dict[str, str] = {"href": url}
         if title:
             attributes["title"] = safe_entity(title)
@@ -90,6 +93,22 @@ class DocsRenderer(HTMLRenderer):
         attrs["class"] = "table is-fullwidth is-bordered"
         return self._make_tag("table", attrs, text)
 
+    def inline_directive(self, text: str, **attrs) -> str:
+        num_dots = text.count(".")
+        display = self.codespan(text)
+
+        if num_dots <= 1:
+            return display
+
+        module, *_ = text.rsplit(".", num_dots - 1)
+        href = f"/api/{module}.html"
+        return self._make_tag(
+            "a",
+            {"href": href, "class": "inline-directive"},
+            display,
+        )
+            
+
     def _make_tag(
         self, tag: str, attributes: dict[str, str], text: str | None = None
     ) -> str:
@@ -126,6 +145,7 @@ _render_markdown = create_markdown(
         "mark",
         "table",
         span,
+        inline_directive,
     ],
 )
 

guide/webapp/display/page/docobject.py

@@ -108,13 +108,31 @@ def _get_object_type(obj) -> str:
 def organize_docobjects(package_name: str) -> dict[str, str]:
     page_content: defaultdict[str, str] = defaultdict(str)
     docobjects = _extract_docobjects(package_name)
+    page_registry: defaultdict[str, list[str]] = defaultdict(list)
     for module, docobject in docobjects.items():
+        print(f"{module=}")
         builder = Builder(name="Partial")
         _docobject_to_html(docobject, builder)
         ref = module.rsplit(".", module.count(".") - 1)[0]
+        page_registry[ref].append(module)
         page_content[f"/api/{ref}.md"] += str(builder)
+    for ref, objects in page_registry.items():
+        page_content[f"/api/{ref}.md"] = _table_of_contents(objects) + page_content[f"/api/{ref}.md"]
     return page_content
 
+def _table_of_contents(objects: list[str]) -> str:
+    builder = Builder(name="Partial")
+    with builder.div(class_="table-of-contents"):
+        builder.h3("Table of Contents", class_="is-size-4")
+        for obj in objects:
+            module, name = obj.rsplit(".", 1)
+            builder.a(
+                E.strong(name), E.small(module),
+                href=f"#{slugify(obj.replace('.', '-'))}",
+                class_="table-of-contents-item",
+            )
+    return str(builder)
+
 
 def _extract_docobjects(package_name: str) -> dict[str, DocObject]:
     docstrings = {}
@@ -310,7 +328,10 @@ def _render_params(builder: Builder, params: list[DocstringParam]) -> None:
                     E.br(),
                     E.span(
                         param.type_name,
-                        class_="has-text-weight-normal has-text-purple ml-2",
+                        class_=(
+                            "has-text-weight-normal has-text-purple "
+                            "is-size-7 ml-2"
+                        ),
                     ),
                 ]
                 dt_args.extend(parts)

guide/webapp/display/plugins/inline_directive.py

@@ -0,0 +1,20 @@
+import re
+
+from mistune.markdown import Markdown
+
+DIRECTIVE_PATTERN = r":(?:class|func|meth|attr|exc|mod|data|const|obj|keyword|option|cmdoption|envvar):`(?P<ref>sanic\.[^`]+)`"  # noqa: E501
+
+def _parse_inline_directive(inline, m: re.Match, state):
+    print("inline_directive.py: _parse_inline_directive", m.group("ref"))
+    state.append_token(
+        {
+            "type": "inline_directive",
+            "attrs": {},
+            "raw": m.group("ref"),
+        }
+    )
+    return m.end()
+
+def inline_directive(md: Markdown):
+    print("Registering inline_directive")
+    md.inline.register("inline_directive", DIRECTIVE_PATTERN, _parse_inline_directive, before="escape",)