Add a custom pydoc renderer for Readme.io

.github/utils/code_and_docs.sh

@@ -18,9 +18,10 @@ echo
 
 echo "==========  Generate the API documentation ========== "
 set -e   # Fails on any error in the following loop
+export PYTHONPATH=$PWD/docs/pydoc # Make the renderers available to pydoc
 cd docs/_src/api/api/
 for file in ../pydoc/* ; do
     echo "Processing" $file
     pydoc-markdown "$file"
 done
-echo 
+echo

docs/_src/api/api/generator.md

@@ -1,3 +1,9 @@
+---
+title: Generators
+excerpt: Use file converters to extract text from files
+category: 62cec7b9c64192049e795c0d
+---
+
 <a id="base"></a>
 
 # Module base

docs/_src/api/pydoc/answer-generator.yml

@@ -5,17 +5,20 @@ loaders:
     ignore_when_discovered: ['__init__']
 processors:
   - type: filter
-    expression: 
+    expression:
     documented_only: true
     do_not_filter_modules: false
     skip_empty_modules: true
   - type: smart
   - type: crossref
 renderer:
-  type: markdown
-  descriptive_class_title: false
-  descriptive_module_title: true
-  add_method_class_prefix: true
-  add_member_class_prefix: false
-  filename: generator.md
-
+  type: renderers.ReadmeRenderer
+  excerpt: Use file converters to extract text from files
+  category: 62cec7b9c64192049e795c0d
+  title: Generators
+  markdown:
+    descriptive_class_title: false
+    descriptive_module_title: true
+    add_method_class_prefix: true
+    add_member_class_prefix: false
+    filename: generator.md

docs/pydoc/renderers.py

@@ -0,0 +1,49 @@
+import sys
+import io
+import dataclasses
+import docspec
+import typing as t
+from pathlib import Path
+from pydoc_markdown.interfaces import Context, Renderer
+from pydoc_markdown.contrib.renderers.markdown import MarkdownRenderer
+
+
+README_FRONTMATTER = """---
+title: {title}
+excerpt: {excerpt}
+category: {category}
+---
+
+"""
+
+
+@dataclasses.dataclass
+class ReadmeRenderer(Renderer):
+    """
+    This custom Renderer is heavily based on the `MarkdownRenderer`,
+    it just prepends a front matter so that the output can be published
+    directly to readme.io.
+    """
+
+    # These settings will be used in the front matter output
+    title: str
+    category: str
+    excerpt: str
+    # This exposes a special `markdown` settings value that can be used to pass
+    # parameters to the underlying `MarkdownRenderer`
+    markdown: MarkdownRenderer = dataclasses.field(default_factory=MarkdownRenderer)
+
+    def init(self, context: Context) -> None:
+        self.markdown.init(context)
+
+    def render(self, modules: t.List[docspec.Module]) -> None:
+        if self.markdown.filename is None:
+            sys.stdout.write(self._frontmatter())
+            self.markdown.render_to_stream(modules, sys.stdout)
+        else:
+            with io.open(self.markdown.filename, "w", encoding=self.markdown.encoding) as fp:
+                fp.write(self._frontmatter())
+                self.markdown.render_to_stream(modules, t.cast(t.TextIO, fp))
+
+    def _frontmatter(self) -> str:
+        return README_FRONTMATTER.format(title=self.title, category=self.category, excerpt=self.excerpt)