made some quarto tweaks (#801)

* removed 1-element sidebar from Community page
* re-added `docs` to linting
* Setup overrides for error F811 for reference generation scripts.
https://www.flake8rules.com/rules/F811.html
* Fixed other linting issues for reference generation scripts

.github/workflows/ci_python.yml

@@ -64,7 +64,7 @@ jobs:
           poetry run black --diff pysrc pytests docs
       - name: flake8
         run: |
-          poetry run flake8 pysrc pytests
+          poetry run flake8 pysrc pytests docs
       - name: isort
         run: |
           poetry run isort --filter-files --diff pysrc pytests docs

python/docs/_quarto.yml

@@ -50,9 +50,6 @@ website:
       - guide/execution.qmd
   - title: Examples
     contents: examples
-  - title: Community
-    contents:
-      - community/index.qmd
   - title: API
     style: docked
     contents: reference

python/docs/_scripts/builder.py

@@ -6,12 +6,17 @@
 from typing import Any, Union
 
 from pydantic import ValidationError
-from quartodoc import blueprint, collect, layout, preview
+from quartodoc import blueprint, collect, layout
 from quartodoc.inventory import convert_inventory, create_inventory
 from quartodoc.validation import fmt
 from renderer import Renderer
 from summarizer import Summarizer
 
+# `preview()` can be used to help debug doc generation.
+# use it on a `section` or `page` element to see a visual
+# representation of the element contents. Use the `max_depth`
+# named param to limit how much is returned to stdout.
+# from quartodoc import preview
 
 _log = logging.getLogger("quartodoc")
 
@@ -176,25 +181,27 @@ def write_pages(self):
                         _log.info(f"Rendering {page.path}")
                         # preview(page, max_depth=4)
                         page_text = self.renderer.render(page)
-                        page_path = location / (page.path + self.out_page_suffix)
+                        page_path = location / \
+                            (page.path + self.out_page_suffix)
                         self.write_page_if_not_exists(page_path, page_text)
                     if page.path in self.page_map:
                         del self.page_map[page.path]
 
                     self.update_page_items(page, location, is_flat)
                 else:
-                    raise NotImplementedError(f"Unsupported section item: {type(page)}")
+                    raise NotImplementedError(
+                        f"Unsupported section item: {type(page)}")
 
         if len(self.page_map.keys()) > 0:
             _log.warning(f"Extra pages: {self.page_map.keys()}")
             _log.error(
-                f"Linking between pages may not work properly. Fix the issue and try again"
+                "Linking between pages may not work properly. Fix the issue and try again"
             )
 
         if len(self.item_map.keys()) > 0:
             _log.warning(f"Extra items: {self.item_map.keys()}")
             _log.error(
-                f"Linking between pages may not work properly. Fix the issue and try again"
+                "Linking between pages may not work properly. Fix the issue and try again"
             )
 
     def update_page_items(self, page: layout.Page, location: Path, is_flat: bool):
@@ -207,7 +214,8 @@ def update_page_items(self, page: layout.Page, location: Path, is_flat: bool):
                 )
                 self.update_items(doc, page_path)
             else:
-                raise NotImplementedError(f"Unsupported page item: {type(doc)}")
+                raise NotImplementedError(
+                    f"Unsupported page item: {type(doc)}")
 
     def update_items(self, doc: layout.Doc, page_path: str):
         name = doc.obj.path
@@ -285,7 +293,8 @@ def from_quarto_config(cls, quarto_cfg: "str | dict"):
 
         cfg = quarto_cfg.get("quartodoc")
         if cfg is None:
-            raise KeyError("No `quartodoc:` section found in your _quarto.yml.")
+            raise KeyError(
+                "No `quartodoc:` section found in your _quarto.yml.")
 
         return Builder(
             **{k: v for k, v in cfg.items()},

python/docs/_scripts/renderer.py

@@ -108,48 +108,52 @@ def _render_table(self, rows, headers):
     # render_annotation method --------------------------------------------------------
 
     @dispatch
-    def render_annotation(self, el: str) -> str:
+    def render_annotation(self, el: str) -> str:  # noqa: F811
         return sanitize(el)
 
     @dispatch
-    def render_annotation(self, el: None) -> str:
+    def render_annotation(self, el: None) -> str:  # noqa: F811
         return ""
 
     @dispatch
-    def render_annotation(self, el: expr.Name) -> str:
+    def render_annotation(self, el: expr.Name) -> str:  # noqa: F811
         if el.full not in skip_annotation_types:
             return f"[{sanitize(el.source)}](`{el.full}`)"
         return ""
 
     @dispatch
-    def render_annotation(self, el: expr.Expression) -> str:
+    def render_annotation(self, el: expr.Expression) -> str:  # noqa: F811
         text = "".join(map(self.render_annotation, el))
         return text.lstrip(".")
 
     # signature method --------------------------------------------------------
 
     @dispatch
-    def signature(self, el: layout.Doc):
+    def signature(self, el: layout.Doc):  # noqa: F811
         return self.signature(el.obj)
 
     @dispatch
-    def signature(self, el: dc.Alias, source: Optional[dc.Alias] = None):
+    def signature(self, el: dc.Alias, source: Optional[dc.Alias] = None):  # noqa: F811
         """Return a string representation of an object's signature."""
         return self.signature(el.target, el)
 
     @dispatch
-    def signature(self, el: dc.Function, source: Optional[dc.Alias] = None) -> str:
+    def signature(  # noqa: F811
+        self, el: dc.Function, source: Optional[dc.Alias] = None
+    ) -> str:
         name = self._get_display_name(source or el)
         pars = self.render(self._fetch_method_parameters(el))
         return f"{name}([{pars}]{{.bold-italic}})"
 
     @dispatch
-    def signature(self, el: dc.Class, source: Optional[dc.Alias] = None) -> str:
+    def signature(  # noqa: F811
+        self, el: dc.Class, source: Optional[dc.Alias] = None
+    ) -> str:
         name = self._get_display_name(source or el)
         return f"***class*** {name}"
 
     @dispatch
-    def signature(
+    def signature(  # noqa: F811
         self, el: Union[dc.Module, dc.Attribute], source: Optional[dc.Alias] = None
     ):
         name = self._get_display_name(source or el)
@@ -158,19 +162,21 @@ def signature(
     # render method -----------------------------------------------------------
 
     @dispatch
-    def render(self, el):
+    def render(self, el):  # noqa: F811
         """Return a string representation of an object, or layout element."""
 
         raise NotImplementedError(f"Unsupported type: {type(el)}")
 
     @dispatch
-    def render(self, el: str):
+    def render(self, el: str):  # noqa: F811
         return el
 
     # render layouts ==========================================================
 
     @dispatch
-    def render(self, el: layout.Section, order: Optional[int] = None) -> str:
+    def render(  # noqa: F811
+        self, el: layout.Section, order: Optional[int] = None
+    ) -> str:
         rows = [self._render_header(el.title or el.subtitle, order=order)]
 
         if el.desc:
@@ -187,7 +193,7 @@ def render(self, el: layout.Section, order: Optional[int] = None) -> str:
         return text
 
     @dispatch
-    def render(self, el: layout.Page, is_flat: bool = False):
+    def render(self, el: layout.Page, is_flat: bool = False):  # noqa: F811
         rows = []
         if el.summary:
             if el.summary.name:
@@ -204,11 +210,11 @@ def render(self, el: layout.Page, is_flat: bool = False):
         return "\n\n".join(rows)
 
     @dispatch
-    def render(self, el: layout.Doc):
+    def render(self, el: layout.Doc):  # noqa: F811
         raise NotImplementedError(f"Unsupported Doc type: {type(el)}")
 
     @dispatch
-    def render(
+    def render(  # noqa: F811
         self, el: Union[layout.DocClass, layout.DocModule], is_flat: bool = False
     ) -> str:
         title = "" if is_flat else self._render_header(el.name)
@@ -230,19 +236,21 @@ def render(
             # add classes
             for raw_class in el.members:
                 if raw_class.obj.is_class and isinstance(raw_class, layout.Doc):
-                    body_rows.extend(self.render(raw_class, is_flat=True).split("\n"))
+                    body_rows.extend(self.render(
+                        raw_class, is_flat=True).split("\n"))
 
             # add methods
             for raw_method in el.members:
                 if raw_method.obj.is_function and isinstance(raw_method, layout.Doc):
-                    body_rows.extend(self.render(raw_method, is_flat=True).split("\n"))
+                    body_rows.extend(self.render(
+                        raw_method, is_flat=True).split("\n"))
 
         text = self._render_definition_list(sig, body_rows)
 
         return "\n\n".join([title, text])
 
     @dispatch
-    def render(self, el: layout.DocFunction, is_flat: bool = False):
+    def render(self, el: layout.DocFunction, is_flat: bool = False):  # noqa: F811
         title = "" if is_flat else self._render_header(el.name)
 
         sig = self.signature(el)
@@ -252,7 +260,7 @@ def render(self, el: layout.DocFunction, is_flat: bool = False):
         return "\n\n".join([title, text])
 
     @dispatch
-    def render(self, el: layout.DocAttribute, is_flat: bool = False):
+    def render(self, el: layout.DocAttribute, is_flat: bool = False):  # noqa: F811
         link = f"[{el.name}](#{el.anchor})"
         description = self.summarizer.summarize(el.obj)
 
@@ -261,7 +269,7 @@ def render(self, el: layout.DocAttribute, is_flat: bool = False):
     # render griffe objects ===================================================
 
     @dispatch
-    def render(self, el: Union[dc.Object, dc.Alias]):
+    def render(self, el: Union[dc.Object, dc.Alias]):  # noqa: F811
         """Render high level objects representing functions, classes, etc.."""
 
         str_body = []
@@ -279,10 +287,11 @@ def render(self, el: Union[dc.Object, dc.Alias]):
     # signature parts -------------------------------------------------------------
 
     @dispatch
-    def render(self, el: dc.Parameters):
+    def render(self, el: dc.Parameters):  # noqa: F811
         # index for switch from positional to kw args (via an unnamed *)
         try:
-            kw_only = [par.kind for par in el].index(dc.ParameterKind.keyword_only)
+            kw_only = [par.kind for par in el].index(
+                dc.ParameterKind.keyword_only)
         except ValueError:
             kw_only = None
 
@@ -318,8 +327,9 @@ def render(self, el: dc.Parameters):
         return ", ".join(pars)
 
     @dispatch
-    def render(self, el: dc.Parameter):
-        splats = {dc.ParameterKind.var_keyword, dc.ParameterKind.var_positional}
+    def render(self, el: dc.Parameter):  # noqa: F811
+        splats = {dc.ParameterKind.var_keyword,
+                  dc.ParameterKind.var_positional}
         has_default = el.default and el.kind not in splats
 
         if el.kind == dc.ParameterKind.var_keyword:
@@ -343,7 +353,7 @@ def render(self, el: dc.Parameter):
     # note this can be a number of things. for example, opening docstring text,
     # or a section with a header not included in the numpydoc standard
     @dispatch
-    def render(self, el: ds.DocstringSectionText):
+    def render(self, el: ds.DocstringSectionText):  # noqa: F811
         new_el = qast.transform(el)
         if isinstance(new_el, ds.DocstringSectionText):
             # ensures we don't recurse forever
@@ -354,7 +364,7 @@ def render(self, el: ds.DocstringSectionText):
     # parameters ----
 
     @dispatch
-    def render(self, el: ds.DocstringSectionParameters):
+    def render(self, el: ds.DocstringSectionParameters):  # noqa: F811
         # if more than one param, render as un-ordered list
         prefix = "* " if len(el.value) > 1 else ""
         follow = "  " if len(el.value) > 1 else ""
@@ -378,7 +388,7 @@ def render(self, el: ds.DocstringSectionParameters):
     # attributes ----
 
     @dispatch
-    def render(self, el: ds.DocstringSectionAttributes):
+    def render(self, el: ds.DocstringSectionAttributes):  # noqa: F811
         # if more than one param, render as un-ordered list
         prefix = "* " if len(el.value) > 1 else ""
         follow = "  " if len(el.value) > 1 else ""
@@ -400,25 +410,25 @@ def render(self, el: ds.DocstringSectionAttributes):
     # examples ----
 
     @dispatch
-    def render(self, el: ds.DocstringSectionExamples):
+    def render(self, el: ds.DocstringSectionExamples):  # noqa: F811
         # its value is a tuple: DocstringSectionKind["text" | "examples"], str
         data = map(qast.transform, el.value)
         return "\n\n".join(list(map(self.render, data)))
 
     @dispatch
-    def render(self, el: qast.ExampleCode):
+    def render(self, el: qast.ExampleCode):  # noqa: F811
         return f"""```python
 {el.value}
 ```"""
 
     @dispatch
-    def render(self, el: qast.ExampleText):
+    def render(self, el: qast.ExampleText):  # noqa: F811
         return el.value
 
     # returns ----
 
     @dispatch
-    def render(self, el: ds.DocstringSectionReturns):
+    def render(self, el: ds.DocstringSectionReturns):  # noqa: F811
         # if more than one param, render as un-ordered list
         prefix = "* " if len(el.value) > 1 else ""
         follow = "  " if len(el.value) > 1 else ""
@@ -446,7 +456,7 @@ def render(self, el: ds.DocstringSectionReturns):
         return self._render_definition_list("Returns:", rows, title_class="highlight")
 
     @dispatch
-    def render(self, el: ds.DocstringSectionRaises):
+    def render(self, el: ds.DocstringSectionRaises):  # noqa: F811
         # if more than one param, render as un-ordered list
         prefix = "* " if len(el.value) > 1 else ""
         follow = "  " if len(el.value) > 1 else ""
@@ -464,14 +474,14 @@ def render(self, el: ds.DocstringSectionRaises):
         return self._render_definition_list("Raises:", rows, title_class="highlight")
 
     @dispatch
-    def render(self, el: ds.DocstringSectionAdmonition) -> str:
+    def render(self, el: ds.DocstringSectionAdmonition) -> str:  # noqa: F811
         rows = []
         if el.title.lower().startswith("note"):
-            rows.append(f'::: {{.callout-note title="{el.title}"}}')
+            rows.append(f"::: {{.callout-note title={el.title!r}}}")
         elif el.title.lower().startswith("warn"):
-            rows.append(f'::: {{.callout-warning title="{el.title}"}}')
+            rows.append(f"::: {{.callout-warning title={el.title!r}}}")
         else:
-            rows.append(f'::: {{.callout-tip title="{el.title}"}}')
+            rows.append(f"::: {{.callout-tip title={el.title!r}}}")
 
         rows.append(el.value.description)
         rows.append(":::")
@@ -488,5 +498,5 @@ def render(self, el: ds.DocstringSectionAdmonition) -> str:
         (ds.DocstringReceive,),
         (ds.DocstringAttribute,),
     )
-    def render(self, el):
+    def render(self, el):  # noqa: F811
         raise NotImplementedError(f"{type(el)}")