flesh out docs

Author: machow

docs/_quarto.yml

@@ -79,12 +79,15 @@ website:
           contents:
             - get-started/basic-docs.qmd
             - get-started/crossrefs.qmd
+            - get-started/sidebar.qmd
         - section: "Advanced"
           contents:
-            - get-started/architecture.qmd
             - get-started/docstrings.qmd
             - get-started/renderers.qmd
             - get-started/interlinks.qmd
+        - section: "Extra Topics"
+          contents:
+            - get-started/architecture.qmd
     - id: dummy
 
 

docs/get-started/crossrefs.qmd

@@ -1,5 +1,5 @@
 ---
-title: Cross references
+title: Linking to pages
 jupyter:
   kernelspec:
     display_name: Python 3 (ipykernel)
@@ -9,21 +9,20 @@ jupyter:
 
 Coming soon!
 
-| style | link text | syntax | output |
-| ----- | ---- | ------ | ------ |
-| manual |  | `[a link](../api/#get_object)` | [a link](../api/#get_object) | 
-| md | custom  | `` [some explanation](`quartodoc.get_object`) `` | [some explanation](`quartodoc.get_object`) |
-| md | default | `` [](`quartodoc.get_object`) `` | [](`quartodoc.get_object`) |
-| md | shortened | `` [](`~quartodoc.get_object`) `` | [](`~quartodoc.get_object`) |
-| rst | custom | `` :ref:`some explanation <quartodoc.get_object>` `` | :ref:`some explanation <quartodoc.get_object>` |
-| rst | default | `` :ref:`quartodoc.get_object` `` | :ref:`quartodoc.get_object` |
-| rst | shortened | `` :ref:`~quartodoc.get_object` `` | :ref:`~quartodoc.get_object` |
+## Linking by path
 
+You can link to function docs by using the path to the generated documentation file:
 
-## Link to external docs
+``[get_object](/reference/get_object.qmd)``
 
-### Inventory files
+
+* /reference/
+
+
+## Linking by function name
 
 
 ## The "See Also" section
 
+
+

docs/get-started/docstrings.qmd

@@ -1,5 +1,5 @@
 ---
-title: Handling docstrings
+title: Inspecting docstrings
 jupyter:
   kernelspec:
     display_name: Python 3 (ipykernel)

docs/get-started/interlinks.qmd

@@ -50,3 +50,17 @@ Where files like `objects_numpy.json` and `objects_python.json` are their invent
 
 The rough idea is that this plugin will behave similar to [jupyterbook linking](https://jupyterbook.org/en/stable/content/references.html),
 which supports both some intersphinx syntax, but also markdown syntax.
+
+## Link formats
+
+| style | link text | syntax | output |
+| ----- | ---- | ------ | ------ |
+| manual |  | `[a link](../api/#get_object)` | [a link](../api/#get_object) | 
+| md | custom  | `` [some explanation](`quartodoc.get_object`) `` | [some explanation](`quartodoc.get_object`) |
+| md | default | `` [](`quartodoc.get_object`) `` | [](`quartodoc.get_object`) |
+| md | shortened | `` [](`~quartodoc.get_object`) `` | [](`~quartodoc.get_object`) |
+| rst | custom | `` :ref:`some explanation <quartodoc.get_object>` `` | :ref:`some explanation <quartodoc.get_object>` |
+| rst | default | `` :ref:`quartodoc.get_object` `` | :ref:`quartodoc.get_object` |
+| rst | shortened | `` :ref:`~quartodoc.get_object` `` | :ref:`~quartodoc.get_object` |
+
+

docs/get-started/sidebar.qmd

@@ -0,0 +1,8 @@
+---
+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.
+
+Generating sidebar entries is being tracked in [this quartodoc issue](https://github.com/machow/quartodoc/issues/20).