docs: better interlinks docs

Author: machow

docs/_quarto.yml

@@ -74,12 +74,12 @@ website:
           contents:
             - get-started/basic-docs.qmd
             - get-started/crossrefs.qmd
+            - get-started/interlinks.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

docs/get-started/crossrefs.qmd

@@ -7,22 +7,46 @@ jupyter:
     name: python3
 ---
 
-Coming soon!
-
 ## Linking by path
 
-You can link to function docs by using the path to the generated documentation file:
-
-``[get_object](/reference/get_object.qmd)``
+You can use [quarto's markdown linking syntax](https://quarto.org/docs/authoring/markdown-basics.html#links-images)
+to link to function docs, by using the path to the generated documentation file.
 
+Here are some examples:
 
-* /reference/
+| code | result |
+| ---- | ------ |
+| ``[get_object](/reference/get_object.qmd)`` | [get_object](/reference/get_object.qmd) |
+| ``[link text](/reference/MdRenderer.qmd)`` | [link text](/reference/MdRenderer.qmd) |
 
 
 ## Linking by function name
 
+Use quartodoc's [interlinking filter](./interlinks.qmd) to link to functions using only their names:
+
+| code | result |
+| ---- | ------ |
+| ``[](`quartodoc.get_object`)`` | [](`quartodoc.get_object`) |
+
+Notice that the link above puts the function name in backticks, rather than using
+the path to its documentation: `` `quartodoc.get_object` ``.
+
+You can also use this approach to link to other documentation sites.
+For example, including links to quartodoc, or https://docs.python.org/3 using function names.
+
+See the [interlinks documentation](./interlinks.qmd) for set up and usage.
+
 
 ## The "See Also" section
 
+A major goal of quartodoc is to automatically turn text in the "See Also" section
+of docstrings into links.
+
+See [this issue](https://github.com/machow/quartodoc/issues/21) for more details
+on parsing See Also sections, and [this issue](https://github.com/machow/quartodoc/issues/22)
+on turning type annotations into links.
 
+## Type annotations in docstrings
 
+This is planned, but currently unimplemented. See [this issue](https://github.com/machow/quartodoc/issues/22)
+on turning type annotations into links.

docs/get-started/interlinks.qmd

@@ -9,25 +9,29 @@ jupyter:
 
 
 The interlinks filter allows you to provide crossreferences within and between documentation.
-It requires of two parts:
+It consists of three pieces:
 
-1. Specifying sphinx inventories for the filter to use in your quarto configuration.
-2. Generating sphinx inventories for the filter to use.
+1. **Install**: adding the extension to your quarto project.
+1. **Configure**: specifying sphinx inventories for the filter to use in your `_quarto.yml` config.
+2. **Run**: Generating sphinx inventories for the filter to use.
 
-## What is a sphinx inventory file?
-
-Sphinx inventory files provide information about where the documentation for
-functions live on a website.
+## Installing
 
-Most sphinx sites name them `object.inv`:
+Use the [quarto add command](https://quarto.org/docs/extensions/filters.html#distribution)
+to install the interlinks filter:
 
-* numpy: https://numpy.org/doc/stable/objects.inv
-* python: https://docs.python.org/3/objects.inv
+```bash
+quarto add machow/quartodoc
+```
 
+:::{.callout-note}
+The code for the filter can be found in quartodoc's
+[_extension folder](https://github.com/machow/quartodoc/tree/main/_extensions/interlinks)
+:::
 
 ## Configuring the interlinks filter
 
-Configure the filter in `_quarto.yml` or on specific pages:
+Configure the filter in `_quarto.yml` or on specific pages, by adding these sections:
 
 ```yaml
 filters:
@@ -41,16 +45,17 @@ interlinks:
       url: https://docs.python.org/3/
 ```
 
-Notice 3 important pieces in this config:
+Notice 2 important pieces in this config:
 
 * The `numpy` and `python` fields indicate that we're getting inventories for the
   library numpy, and python builtin libraries.
 * The `url` fields indicate where inventory files can be found.
-* The `fallback` field indicates where we should save the file, so we don't need
-  to download it repeatedly.
 
+By default, downloaded inventory files will be saved in the `_inv` folder of your
+documentation directory.
 
-## Generating sphinx inventories
+
+## Running the interlinks filter
 
 First, build the reference for your own site, which includes an objects.json inventory:
 
@@ -127,6 +132,20 @@ For example, python.org has two entries for the name `print`.
 | py | function | [``[](:py:function:`print`)``](:py:function:`print`) |
 
 
+## What is a sphinx inventory file?
+
+Sphinx inventory files provide information about where the documentation for
+functions live on a website.
+
+Most sphinx sites name them `object.inv`:
+
+* numpy: https://numpy.org/doc/stable/objects.inv
+* python: https://docs.python.org/3/objects.inv
+
+See the [sphobjinv docs](https://sphobjinv.readthedocs.io/en/stable/) for thorough
+details on these files, and how they're used in sphinx.
+
+
 ## More information
 
 Under the hood, quarto doc generates sphinx inventories for an API e using [create_inventory](/api/#sec-create_inventory),