Merge pull request #28 from machow/example-shiny

Example shiny

Author: machow

.github/workflows/ci.yml

@@ -78,6 +78,7 @@ jobs:
         run: |
           python -m pip install -r requirements-dev.txt
           python -m pip install .
+          python -m pip install shiny shinylive
       - uses: quarto-dev/quarto-actions/setup@v2
       - name: Build docs
         run: |

Makefile

@@ -2,14 +2,18 @@ README.md: README.qmd
 	quarto render $<
 
 examples/%/_site: examples/%/_quarto.yml
-	python -m quartodoc build $<
+	cd examples/$* \
+		&& quarto add --no-prompt ../.. \
+		&& quarto add --no-prompt quarto-ext/shinylive
+	cd examples/$* && python -m quartodoc build _quarto.yml --verbose
+	cd examples/$* && python -m quartodoc interlinks
 	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-examples: docs/examples/single-page docs/examples/pkgdown docs/examples/shiny
 
 docs-build: docs-build-examples
 	cd docs && quarto add --no-prompt ..

_extensions/interlinks/interlinks.py

@@ -47,6 +47,10 @@ def lookup_reference(self, ref: Ref):
             else:
                 field_value = getattr(ref, field)
 
+            if field == "role":
+                # for some reason, things like :func: are short for :function:.
+                field_value = self.normalize_role(field_value)
+
             crnt_items = _filter_by_field(crnt_items, field, field_value)
 
         results = list(crnt_items)
@@ -65,6 +69,12 @@ def lookup_reference(self, ref: Ref):
 
         return results[0]
 
+    def normalize_role(self, role_name):
+        if role_name == "func":
+            return "function"
+
+        return role_name
+
 
 global_inventory = Inventories()
 
@@ -80,7 +90,12 @@ def get_path_to_root():
     # I have no idea how to get the documentation root,
     # except to get the path the extension script, which
     # lives in <root>/_extensions/interlinks, and work back
-    return Path(__file__).parent.parent.parent
+    p_root = Path(__file__).parent.parent.parent
+
+    if p_root.name == "_extensions":
+        return p_root.parent
+
+    return p_root
 
 
 def load_inventories(interlinks: dict):
@@ -189,14 +204,8 @@ def parse_rst_style_ref(full_text):
 # Visitor ================================================================================
 
 
-@dispatch
-def visit(el, doc):
-    return el
-    # raise TypeError(f"Unsupported type: {type(el)}")
-
+def prepare(doc: pf.Doc):
 
-@dispatch
-def visit(el: pf.MetaList, doc):
     meta = doc.get_metadata()
 
     try:
@@ -212,12 +221,13 @@ def visit(el: pf.MetaList, doc):
 
     load_inventories(interlinks)
 
-    return el
+    return doc
 
 
 @dispatch
-def visit(el: pf.Doc, doc):
+def visit(el, doc):
     return el
+    # raise TypeError(f"Unsupported type: {type(el)}")
 
 
 # TODO: the syntax :ref:`target` is not trivial to implement. The pandoc AST
@@ -251,7 +261,7 @@ def visit(el: pf.Link, doc):
 
 
 def main(doc=None):
-    return pf.run_filter(visit, doc=None)
+    return pf.run_filter(visit, prepare=prepare, doc=None)
 
 
 if __name__ == "__main__":

docs/_quarto.yml

@@ -4,6 +4,10 @@ project:
   resources:
     - examples/single-page
     - examples/pkgdown
+    - examples/shiny
+
+metadata-files:
+  - api/_sidebar.yml
 
 filters:
   - "interlinks"
@@ -12,11 +16,14 @@ interlinks:
   sources:
     python:
       url: https://docs.python.org/3/
+    griffe:
+      url: https://mkdocstrings.github.io/griffe/
 
 quartodoc:
   style: pkgdown
   dir: api
   package: quartodoc
+  sidebar: "api/_sidebar.yml"
   sections:
     - title: API Builders
       desc: |
@@ -83,7 +90,6 @@ website:
         - section: "Extra Topics"
           contents:
             - get-started/architecture.qmd
-    - id: dummy
 
 
 format:

docs/examples/index.qmd

@@ -2,10 +2,13 @@
 | ----- | ------ | ------ |
 | [pkgdown] | [github][pkgdown-code] | Index page with a title and short description for functions listed in each section. Each function gets its own documentation page. |
 | [single-page] | [github][sp-code] | Index page has function documentation embedded on it. |
+| [shiny] | [github][shiny-code] | The shiny docs translated to quartodoc, using a custom renderer. |
 
 : {tbl-colwidths="[20, 20, 60]"}
 
 [pkgdown]: /examples/pkgdown/reference
 [pkgdown-code]: https://github.com/machow/quartodoc/tree/main/examples/pkgdown
 [single-page]: /examples/single-page/reference
 [sp-code]: https://github.com/machow/quartodoc/tree/main/examples/single-page
+[shiny]: /examples/shiny/reference
+[shiny-code]: https://github.com/machow/quartodoc/tree/main/examples/shiny

docs/get-started/sidebar.qmd

@@ -2,7 +2,31 @@
 title: Sidebar navigation
 ---
 
-Currently, adding API reference pages to the left-hand sidebar requires manually
-listing each page in `_quarto.yml`. See the [quarto sidebar docs](https://quarto.org/docs/websites/website-navigation.html#side-navigation) for details.
+quartodoc can generate a sidebar on the lefthand side of the page, with a list of your functions.
 
-Generating sidebar entries is being tracked in [this quartodoc issue](https://github.com/machow/quartodoc/issues/20).
+In order to create a sidebar for your docs, add the following options to your `_quarto.yml`:
+
+```yaml
+# tell quarto to read the sidebar file
+metadata-files:
+  - _sidebar.yml
+
+
+# tell quartodoc to generate the sidebar file
+quartodoc:
+  sidebar: "_sidebar.yml"
+  # other options ...
+```
+
+Note that running `python -m quartodoc build` will now produce a file called `_sidebar.yml`,
+with a [quarto sidebar configuration](https://quarto.org/docs/websites/website-navigation.html#side-navigation).
+The quarto [`metadata-files` option](https://quarto.org/docs/projects/quarto-projects.html#metadata-includes) ensures
+it's included with the configuration in `_quarto.yml`.
+
+Here is what the sidebar for the [quartodoc reference page](/api) looks like:
+
+<div class="sourceCode">
+<pre class="sourceCode yaml"><code class="sourceCode yaml">
+{{< include /api/_sidebar.yml >}}
+</code></pre>
+</div>

examples/pkgdown/reference/get_object.qmd

@@ -1,18 +1,20 @@
 ## get_object { #get_object }
 
-`get_object(module: str, object_name: str, parser: str = 'numpy')`
+`get_object(module, object_name, parser='numpy', load_aliases=True, modules_collection=None)`
 
 Fetch a griffe object.
 
 ### Parameters
 
-| Name          | Type   | Description                | Default   |
-|---------------|--------|----------------------------|-----------|
-| `module`      | str    | A module name.             | required  |
-| `object_name` | str    | A function name.           | required  |
-| `parser`      | str    | A docstring parser to use. | `'numpy'` |
+| Name                 | Type                      | Description                                                                        | Default   |
+|----------------------|---------------------------|------------------------------------------------------------------------------------|-----------|
+| `module`             | str                       | A module name.                                                                     | required  |
+| `object_name`        | str                       | A function name.                                                                   | required  |
+| `parser`             | str                       | A docstring parser to use.                                                         | `'numpy'` |
+| `load_aliases`       |                           | For aliases that were imported from other modules, should we load that module?     | `True`    |
+| `modules_collection` | None \| ModulesCollection | A griffe [](`~griffe.collections.ModulesCollection`), used to hold loaded modules. | `None`    |
 
-### See_Also
+### See Also
 
 get_function: a deprecated function.
 

examples/pkgdown/reference/preview.qmd

@@ -1,6 +1,6 @@
 ## preview { #preview }
 
-`preview(ast: dc.Object | ds.Docstring | object, max_depth=999)`
+`preview(ast, max_depth=999)`
 
 Print a friendly representation of a griffe object (e.g. function, docstring)
 

examples/shiny/.gitignore

@@ -0,0 +1,9 @@
+# vim
+.*.sw[po]
+
+# quartodoc api folder
+reference
+
+# quarto
+/.quarto/
+_site