docs: fix examples

Author: machow

Makefile

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

docs/_quarto.yml

@@ -3,6 +3,8 @@ project:
   output-dir: _build
   resources:
     - objects.json
+    - examples/single-page
+    - examples/pkgdown
   #pre-render: "python -m quartodoc _quarto.yml"
 
 filters:
@@ -59,6 +61,8 @@ website:
     left:
       - file: get-started/overview.qmd
         text: Get Started
+      - file: examples/
+        text: Examples
       - href: api/
         text: Reference
     right:

examples/pkgdown/.gitignore

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

examples/pkgdown/_quarto.yml

@@ -0,0 +1,28 @@
+project:
+  type: website
+  resources:
+    - objects.json
+
+website:
+  navbar:
+    left:
+      - href: https://machow.github.io/quartodoc/
+        text: quartodoc home
+      - file: reference/index.qmd
+        text: "Reference"
+    right:
+      - icon: github
+        href: https://github.com/machow/quartodoc/tree/main/examples/pkgdown
+
+
+
+quartodoc:
+  style: pkgdown
+  dir: reference
+  package: quartodoc
+  sections:
+    - title: Some functions
+      desc: These functions inspect and parse docstrings.
+      contents:
+        - get_object
+        - preview

examples/pkgdown/objects.json

@@ -0,0 +1 @@
+{"project": "quartodoc", "version": "0.0.9999", "count": 2, "items": [{"name": "quartodoc.get_object", "domain": "py", "role": "function", "priority": "1", "uri": "reference/get_object.html", "dispname": "get_object"}, {"name": "quartodoc.preview", "domain": "py", "role": "function", "priority": "1", "uri": "reference/preview.html", "dispname": "preview"}]}

examples/pkgdown/reference/get_object.qmd

@@ -0,0 +1,24 @@
+## get_object { #get_object }
+
+`get_object(module: str, object_name: str, parser: str = 'numpy')`
+
+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'` |
+
+See Also
+--------
+get_function: a deprecated function.
+
+### Examples
+
+```python
+>>> get_function("quartodoc", "get_function")
+<Function('get_function', ...
+```

examples/pkgdown/reference/index.qmd

@@ -0,0 +1,10 @@
+# Function reference
+
+## Some functions
+
+These functions inspect and parse docstrings.
+
+| | |
+| --- | --- |
+| [get_object](/reference/get_object.qmd) | Fetch a griffe object. |
+| [preview](/reference/preview.qmd) | Print a friendly representation of a griffe object (e.g. function, docstring) |

examples/pkgdown/reference/preview.qmd

@@ -0,0 +1,22 @@
+## preview { #preview }
+
+`preview(ast: dc.Object | ds.Docstring | object)`
+
+Print a friendly representation of a griffe object (e.g. function, docstring)
+
+### Examples
+
+```python
+>>> from quartodoc import get_object
+>>> obj = get_object("quartodoc", "get_object")
+```
+
+```python
+>>> preview(obj.docstring.parsed)
+ ...
+```
+
+```python
+>>> preview(obj)
+ ...
+```

examples/single-page/.gitignore

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

examples/single-page/_quarto.yml

@@ -0,0 +1,26 @@
+project:
+  type: website
+  resources:
+    - objects.json
+
+website:
+  navbar:
+    left:
+      - href: https://machow.github.io/quartodoc/
+        text: quartodoc home
+      - file: reference/index.qmd
+        text: "Reference"
+    right:
+      - icon: github
+        href: https://github.com/machow/quartodoc/tree/main/examples/single-page
+
+quartodoc:
+  style: single-page
+  dir: reference
+  package: quartodoc
+  sections:
+    - title: Some functions
+      desc: These functions inspect and parse docstrings.
+      contents:
+        - get_object
+        - preview