Merge pull request #15 from machow/docs-interlinks

docs: flesh out interlinks page

Author: machow

docs/get-started/interlinks.qmd

@@ -7,6 +7,46 @@ jupyter:
     name: python3
 ---
 
-Coming soon!
+Coming soon! See the [interlinks folder](https://github.com/machow/quartodoc/tree/main/interlinks), which defines a WIP quarto filter for providing crossrefs.
 
-See the [interlinks folder](https://github.com/machow/quartodoc/tree/main/interlinks), which defines a WIP quarto filter for providing crossrefs.
+The interlinks filter allows you to provide crossreferences within and between documentation.
+It requires of two parts:
+
+1. Generating a sphinx inventory for your own docs.
+2. Specifying sphinx inventories for the filter to use in your quarto configuration.
+
+## Generating a sphinx inventory
+
+A sphinx inventory file, generated by [create_inventory](/api/#sec-create_inventory),
+and then dumped to JSON using [convert_inventory](/api/#sec-convert_inventory).
+
+For an overview of the sphinx inventory format, see [the sphobjinv docs](https://sphobjinv.readthedocs.io)
+
+## Configuring the interlinks filter
+
+Configure the filter in `_quarto.yml` or on specific pages:
+
+```
+filters:
+  - interlinks
+interlinks:
+  sources:
+    numpy:
+      url: https://numpy.org/doc/stable/
+      inv: null 
+      fallback: objects_numpy.json
+    python:
+      url: https://docs.python.org/3/
+      inv: null
+      fallback: objects_python.json
+```
+
+Where files like `objects_numpy.json` and `objects_python.json` are their inventories converted to JSON, using the functions from the section above.
+
+`objects.inv` live at the root of sphinx project urls:
+
+* numpy: https://numpy.org/doc/stable/objects.inv
+* python: https://docs.python.org/3/objects.inv
+
+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.

docs/get-started/overview.qmd

@@ -7,6 +7,11 @@ jupyter:
     name: python3
 ---
 
+::: {.callout-warning} 
+quartodoc is work in progress! For a basic implementation, take a look at the [docs folder](https://github.com/machow/quartodoc/tree/main/docs) for this site,
+including [this script](https://github.com/machow/quartodoc/blob/main/docs/1_generate_api.py) used to generate API pages.
+:::
+
 Coming soon!
 
 ## Goals

docs/index.qmd

@@ -2,6 +2,11 @@
 title: "quartodoc"
 ---
 
+::: {.callout-warning} 
+quartodoc is work in progress! For a basic implementation, take a look at the [docs folder](https://github.com/machow/quartodoc/tree/main/docs) for this site,
+including [this script](https://github.com/machow/quartodoc/blob/main/docs/1_generate_api.py) used to generate API pages.
+:::
+
 For users:
 
 * Read and interact with docstrings.