Merge pull request #311 from has2k1/more-extendable-quartodoc

More extendable quartodoc

Author: machow

quartodoc/autosummary.py

@@ -22,6 +22,8 @@
 from .renderers import Renderer
 from .validation import fmt_all
 from ._pydantic_compat import ValidationError
+from .pandoc.blocks import Blocks, Header
+from .pandoc.components import Attr
 
 
 from typing import Any
@@ -463,6 +465,8 @@ class Builder:
     title: str
 
     renderer: Renderer
+    items: list[layout.Item]
+    """Documented items by this builder"""
 
     def __init_subclass__(cls, **kwargs):
         super().__init_subclass__(**kwargs)
@@ -553,7 +557,7 @@ def build(self, filter: str = "*"):
         blueprint = blueprint(self.layout, dynamic=self.dynamic, parser=self.parser)
 
         _log.info("Collecting pages and inventory items.")
-        pages, items = collect(blueprint, base_dir=self.dir)
+        pages, self.items = collect(blueprint, base_dir=self.dir)
 
         # writing pages ----
 
@@ -562,11 +566,12 @@ def build(self, filter: str = "*"):
 
         _log.info("Writing docs pages")
         self.write_doc_pages(pages, filter)
+        self.renderer._pages_written(self)
 
         # inventory ----
 
         _log.info("Creating inventory file")
-        inv = self.create_inventory(items)
+        inv = self.create_inventory(self.items)
         if self._fast_inventory:
             # dump the inventory file directly as text
             # TODO: copied from __main__.py, should add to inventory.py
@@ -591,7 +596,9 @@ def write_index(self, blueprint: layout.Layout):
         content = self.renderer.summarize(blueprint)
         _log.info(f"Writing index to directory: {self.dir}")
 
-        final = f"# {self.title}\n\n{content}"
+        final = str(
+            Blocks([Header(1, self.title, Attr(classes=["doc", "doc-index"])), content])
+        )
 
         p_index = Path(self.dir) / self.out_index
         p_index.parent.mkdir(exist_ok=True, parents=True)

quartodoc/renderers/base.py

@@ -1,7 +1,10 @@
 import re
+import typing
 
 from plum import dispatch
 
+if typing.TYPE_CHECKING:
+    from ..autosummary import Builder
 
 # utils -----------------------------------------------------------------------
 
@@ -81,3 +84,23 @@ def from_config(cls, cfg: "dict | Renderer | str"):
     @dispatch
     def render(self, el):
         raise NotImplementedError(f"render method does not support type: {type(el)}")
+
+    def _pages_written(self, builder: "Builder"):
+        """
+        Called after all the qmd pages have been render and written to disk
+
+        It is called before the documented items are written to an inventory
+        file. This is a chance for the renderer to add to the documented items
+        and write the pages to them to disk.
+
+        Parameters
+        ----------
+        builder :
+            There builder using this renderer to generate documentation.
+
+        Notes
+        -----
+        This method is provided for experimental purposes and it is not bound
+        to be available for long, or have the same form.
+        """
+        ...