Merge pull request #18 from machow/feat-builder

Feat builder

Author: machow

Makefile

@@ -1,8 +1,19 @@
 README.md: README.qmd
 	quarto render $<
 
-docs-build:
+examples/%/_site: examples/%/_quarto.yml
+	python -m quartodoc $<
+	quarto render $(dir $<)
+
+docs/examples/%: examples/%/_site
+	rm -rf docs/examples/$*
+	cp -rv $< $@
+
+docs-build-examples: docs/examples/single-page docs/examples/pkgdown
+
+docs-build: docs-build-examples
 	cd docs && quarto add --no-prompt ..
+	cd docs && python -m quartodoc
 	quarto render docs
 
 requirements-dev.txt:

README.qmd

@@ -31,6 +31,8 @@ python3 -m pip install -e git+https://github.com/machow/quartodoc.git#egg=quarto
 
 ## Basic use
 
+### Render a docstring
+
 ```{python}
 #| output: false
 
@@ -68,6 +70,27 @@ print(
     <Function('get_function', ...
     ```
 
+### Build an index page
+
+```{python}
+#| output: false
+
+from quartodoc.autosummary import BuilderPkgdown
+
+builder = BuilderPkgdown(
+    [
+        {"title": "first", "desc": "section 1", "contents": ["get_object", "get_function"]},
+        {"title": "2nd", "desc": "section 2", "contents": ["MdRenderer"]}
+    ],
+    "quartodoc"
+    )
+
+print(
+    builder.render_index()
+)
+    
+```
+
 
 
 ## How it works

_extensions/interlinks/interlinks.lua

@@ -48,12 +48,14 @@ def ref_to_anchor(ref: str, text: "str | pf.ListContainer | None"):
     except KeyError:
         raise KeyError(f"Cross reference not found in an inventory file: {stripped}")
 
+    pf.debug(f"TEXT IS: {text}")
     if not text:
+        name = entry["name"] if entry["dispname"] == "-" else entry["dispname"]
         if is_shortened:
             # shorten names from module.sub_module.func_name -> func_name
-            name = pf.Str(entry["name"].split(".")[-1])
+            name = pf.Str(name.split(".")[-1])
         else:
-            name = pf.Str(entry["name"])
+            name = pf.Str(name)
     else:
         # when the element is an Link, content is a ListContainer, but it has to be
         # *splatted back into Link?

_extensions/interlinks/interlinks.py

@@ -1,2 +1,6 @@
 /.quarto/
 _site
+reference
+
+examples/pkgdown
+examples/single-page

docs/.gitignore

@@ -3,24 +3,66 @@ project:
   output-dir: _build
   resources:
     - objects.json
+    - examples/single-page
+    - examples/pkgdown
+  #pre-render: "python -m quartodoc _quarto.yml"
 
 filters:
   - "interlinks"
 
 interlinks:
   sources:
     quartodoc:
-      # TODO: how to have it be "site root"?
+      # TODO: add note that this works as the site root
       url: "/"
       inv: null
       fallback: objects.json
 
+quartodoc:
+  style: pkgdown
+  dir: api
+  package: quartodoc
+  sections:
+    - title: API Builders
+      desc: |
+        Builders are responsible for building documentation. They tie all the pieces
+        of quartodoc together, and can be defined in your _quarto.yml config.
+      contents:
+        - Builder
+        - BuilderPkgdown
+        - BuilderSinglePage
+
+    - title: Docstring Renderers
+      desc: |
+        Renderers convert parsed docstrings into a target format, like markdown.
+      contents:
+        - MdRenderer
+
+    - title: Inspection
+      desc: |
+        These functions Fetch and analyze python objects, including parsing docstrings.
+      contents:
+        - get_object
+        - preview
+
+    - title: Inventory links
+      desc: |
+        Inventory files map a functions name to its corresponding url in your docs.
+        These functions allow you to create and transform inventory files.
+      contents:
+        - create_inventory
+        - convert_inventory
+
+
 website:
   title: "quartodoc"
+  page-navigation: true
   navbar:
     left:
       - file: get-started/overview.qmd
         text: Get Started
+      - file: examples/
+        text: Examples
       - href: api/
         text: Reference
     right:
@@ -32,15 +74,20 @@ website:
       style: floating
       align: left
       contents:
+        - get-started/overview.qmd
         - section: "Basics"
           contents:
-            - get-started/overview.qmd
             - get-started/basic-docs.qmd
             - get-started/crossrefs.qmd
+            - get-started/sidebar.qmd
         - section: "Advanced"
           contents:
             - get-started/docstrings.qmd
+            - get-started/renderers.qmd
             - get-started/interlinks.qmd
+        - section: "Extra Topics"
+          contents:
+            - get-started/architecture.qmd
     - id: dummy