Doc updates

docs_src/.gitignore

@@ -0,0 +1 @@
+/.quarto/

docs_src/_quarto.yml

@@ -0,0 +1,92 @@
+## Build the docs by cd'ing into docs and doing: 
+## quarto render .
+## python -m quartodoc build
+## python gen_api_custom.py
+project:
+  type: website
+  output-dir: ../docs
+
+quartodoc: 
+  package: simplextree
+  title: API Reference    # API only 
+  dir: reference          # API only 
+  style: pkgdown          # API only
+  sidebar: _sidebar.yml 
+
+  renderer: 
+    style: _renderer.py
+    show_signature: true
+    show_signature_annotations: true
+    display_name: name 
+
+  sections: 
+    - title: Simplex Tree
+      desc: The Simplex Tree datastructure. 
+      contents:
+        - name: SimplexTree
+          dynamic: true
+          members: 
+            - faces
+
+
+website:
+  title: simplextree
+  search: 
+    location: sidebar
+    type: textbox
+  navbar:
+    background: light
+    right: 
+      - icon: github
+        href: https://github.com/peekxc/simplextree-py
+    pinned: false  
+    search: false       
+  sidebar:
+    style: "docked"
+    pinned: false
+    align: center 
+    search: true
+    border: true 
+    collapse-level: 2
+    contents: 
+      - text: Overview 
+        href: pages/overview.qmd
+      - section: API Reference
+        href: reference/index.qmd
+        contents:
+          - name: SimplexTree 
+            text: Simplex Tree
+            href: reference/UnionFind.UnionFind.qmd
+          - name: UnionFind 
+            text: Union Find
+            href: reference/UnionFind.UnionFind.qmd
+
+  page-navigation: true
+  reader-mode: true
+  page-footer: 
+    center: "Copyright 2023, Matthew Piekenbrock" 
+    border: true
+
+latex-auto-install: true 
+
+execute:
+  cache: true
+
+theme: 
+  light: flatly
+  dark: darkly
+
+format:
+  html: 
+    anchor-selections: true 
+    code-fold: false
+    smooth-scroll: true
+    html-math-method: katex
+    code-overflow: wrap 
+    highlight-style: printing 
+    fontsize: 14px
+    linestretch: 1.3
+    margin-top: "0px" 
+    css: static/styles.css
+# out_index: pages/index.qmd
+# sphinx-build . ./_build/html -b html

docs_src/_renderer.py

@@ -0,0 +1,156 @@
+from quartodoc import MdRenderer
+from griffe import dataclasses as dc
+from griffe.docstrings import dataclasses as ds
+from plum import dispatch
+from tabulate import tabulate
+from typing import *
+from griffe.expressions import ExprName, Expr
+from quartodoc.renderers import *
+from quartodoc.ast import ExampleCode, ExampleText
+
+_UNHANDLED = []
+
+class Renderer(MdRenderer):
+  style = "markdown_numpy"
+  display_name = 'name'
+  show_signature_annotations = True 
+
+  def __init__(self, *args, **kwargs):
+    super().__init__()
+
+  # def _fetch_object_dispname(self, el: "dc.Alias | dc.Object"):
+  #   if self.display_name == "parent":
+  #     return el.parent.name + "." + el.name
+  #   else: 
+  #     return super(Renderer, self).render(el)
+
+  # Keep admonition at the top here ----
+  @dispatch
+  def render(self, el: ds.DocstringSectionAdmonition) -> str:
+    _UNHANDLED.append(el)
+    return "UNHANDLED ADMONITION"
+
+
+  # Parameters ----
+  @dispatch
+  def render(self, el: ds.DocstringSectionParameters) -> str:
+    params_str = []
+    for ds_param in el.value:
+      d = ds_param.as_dict()
+      pn, pa, pd = [d.get(k) for k in ("name", "annotation", "description")]
+      sec_md = f"**{pn}** : "
+      if isinstance(pa, ExprName) or isinstance(pa, Expr):
+        sec_md += f"<span class='type_annotation'> {pa.full}, </span>"
+      else: 
+        sec_md += "" if pa is None or len(str(pa)) == 0 else str(pa)+", "
+      sec_md += f"optional (default={ d.get('value') })" if "value" in d.keys() else "required"
+      sec_md += f"<p> {pd} </p>" 
+      params_str.append(sec_md)
+    return "\n\n".join(params_str)
+
+  # @dispatch
+  # def render(self, el: dc.Parameters):
+  #   return super(Renderer, self).render(el)
+
+  # @dispatch
+  # def render(self, el: dc.Parameter):
+  #   return super(Renderer, self).render(el)
+
+  # # returns ----
+  @dispatch
+  def render(self, el: Union[ds.DocstringSectionReturns, ds.DocstringSectionRaises]) -> str:
+    params_str = []
+    for ds_param in el.value:
+      d = ds_param.as_dict()
+      pn, pa, pd = [d.get(k) for k in ("name", "annotation", "description")]
+      sec_md = f"**{pn}** : "
+      if isinstance(pa, ExprName) or isinstance(pa, Expr):
+        sec_md += f"<span class='type_annotation'> {pa.full}, </span>"
+      else: 
+        sec_md += "" if pa is None or len(str(pa)) == 0 else str(pa)+", "
+      sec_md += f"<p> {pd} </p>" #style='margin-top: 10px;margin-left: 2.5em;
+      params_str.append(sec_md)
+    return "\n\n".join(params_str)
+
+    @dispatch
+    def render(self, el: dc.Parameter):
+      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:
+          glob = "**"
+      elif el.kind == dc.ParameterKind.var_positional:
+          glob = "*"
+      else:
+          glob = ""
+
+      annotation = self.render_annotation(el.annotation)
+      if self.show_signature_annotations:
+          if annotation and has_default:
+              res = f"{glob}{el.name}: {el.annotation} = {el.default}"
+          elif annotation:
+              res = f"{glob}{el.name}: {el.annotation}"
+      elif has_default:
+          res = f"{glob}{el.name}={el.default}"
+      else:
+          res = f"{glob}{el.name}"
+
+      return sanitize(res)
+
+  # ## This shouldn't be triggered 
+  # @dispatch
+  # def render(self, el: Union[ds.DocstringReturn, ds.DocstringRaise]):
+  #   _UNHANDLED.append(el)
+  #   return "UNHANDLED RETURN"
+
+  # --- Attributes
+  @dispatch
+  def render(self, el: ds.DocstringAttribute) -> str :
+    _UNHANDLED.append(el)
+    d = ds_attr.as_dict()
+    pn, pa, pd = [d.get(k) for k in ("name", "annotation", "description")]
+    # return [pn, self._render_annotation(pa), pd]
+    return "UNHANDLED ATTRIBUTE" 
+
+  @dispatch
+  def render(self, el: ds.DocstringSectionAttributes):
+    header = ["Name", "Type", "Description"]
+    rows = []
+    for ds_attr in el.value:
+      d = ds_attr.as_dict()
+      pn, pa, pd = [d.get(k) for k in ("name", "annotation", "description")]
+      rows.append([pn, self.render_annotation(pa), pd])
+    return tabulate(rows, header, tablefmt="github")
+
+  ## examples ----
+  # @dispatch
+  # def render(self, el: ds.DocstringSectionExamples) -> str:
+  #   return super(Renderer, self).render(el)
+
+  # @dispatch
+  # def render(self, el: ExampleText) -> str:
+  #   return super(Renderer, self).render(el)
+
+  # ## Sections ---   
+  # @dispatch
+  # def render(self, el: ds.DocstringSectionText):
+  #   return super(Renderer, self).render(el)
+
+  # @dispatch
+  # def render(self, el: ds.DocstringSection):
+  #   _UNHANDLED.append(el)
+  #   return "UNHANDLED SECTION"
+
+  # @dispatch
+  # def render(self, el: ExampleCode):
+  #   return "```{python}\n" + el.value + "\n```"
+
+  # @dispatch
+  # def render(self, el) -> str:
+  #   #raise NotImplementedError(f"Unsupported type of: {type(el)}")
+  #   _UNHANDLED.append(el)
+  #   import warnings
+  #   warnings.warn(f"Unsupported type of: {type(el)}")
+  #   return ""
+
+

docs_src/_sidebar.yml

@@ -0,0 +1,9 @@
+website:
+  sidebar:
+  - contents:
+    - reference/index.qmd
+    - contents:
+      - reference/VERSION.qmd
+      section: SimplexTree
+    id: reference
+  - id: dummy-sidebar

docs_src/gen_api.py

@@ -0,0 +1,44 @@
+import yaml
+import quartodoc
+from quartodoc import Builder, preview, blueprint, collect, MdRenderer
+from quartodoc.builder.blueprint import BlueprintTransformer
+from _renderer import Renderer as NumpyRenderer
+
+## Configure builder 
+cfg = yaml.safe_load(open("_quarto.yml", "r"))
+builder = Builder.from_quarto_config(cfg)
+# builder.renderer = NumpyRenderer()
+
+# builder.renderer = MdRenderer(show_signature=True, show_signature_annotations=True, display_name="name")
+# builder.renderer.display_name = 'name'
+# builder.renderer.show_signature_annotations = True 
+
+## Blueprint + collect  using google style parsing 
+trans = BlueprintTransformer(parser="google")
+bp = trans.visit(builder.layout)
+pages, items = collect(bp, builder.dir)
+
+builder.layout.sections[0].package = 'simplextree'
+
+## Write the doc pages + the index  
+builder.write_doc_pages(pages, "*")
+builder.write_index(bp)
+# builder.write_sidebar(bp)
+
+# ## Simplex Tree
+# preview(builder.layout.sections[0])
+
+# ## The markdown text of each individual page...
+# [renderer.render(p) for p in pages]
+
+# preview(bp.sections[0], max_depth=8, compact=True)
+# preview(bp.sections[0].contents[0].contents[0])
+
+# ## Rendering individual docstrings 
+# from quartodoc import get_object
+# st_doc = get_object("splex.complexes", "SimplexTree.SimplexTree", parser="google")
+# preview(st_doc.members['insert'], compact=True)
+
+# from quartodoc.renderers import MdRenderer
+# renderer = MdRenderer(header_level=2)
+# print(renderer.render(st_doc.members['insert']))

docs_src/objects.json

@@ -0,0 +1 @@
+{"project": "simplextree", "version": "0.0.9999", "count": 1, "items": [{"name": "simplextree.VERSION", "domain": "py", "role": "attribute", "priority": "1", "uri": "reference/VERSION.html#simplextree.VERSION", "dispname": "-"}]}