docs: use interlinks filter

Author: machow

docs/1_generate_api.py

@@ -9,6 +9,8 @@
     __version__,
 )
 
+# Settings --------------------------------------------------------------------
+
 FUNCTIONS = [
     "get_object",
     "create_inventory",
@@ -17,16 +19,17 @@
 ]
 
 PACKAGE = "quartodoc"
+API_FOLDER = "api"
 
 # +
 root = Path(sys.argv[0]).parent
 renderer = MdRenderer(header_level=1)
 
-p = root / "api"
+p = root / API_FOLDER
 p.mkdir(exist_ok=True)
 # -
 
-# Stage 1: inventory file ----
+# Stage 1: inventory file -----------------------------------------------------
 all_objects = []
 for name in FUNCTIONS:
     all_objects.append(get_object(PACKAGE, name))
@@ -35,12 +38,12 @@
     PACKAGE,
     __version__,
     all_objects,
-    uri=lambda s: f"api/#{s.name}",
+    uri=lambda s: f"{API_FOLDER}/#{s.name}",
     dispname=lambda s: f"{s.name}",
 )
 convert_inventory(inv, "objects.json")
 
-# Stage 2: render api pages ----
+# Stage 2: render api pages ---------------------------------------------------
 all_content = []
 for f_obj in all_objects:
     print(f_obj.name)

docs/_extensions/interlinks

@@ -0,0 +1 @@
+../../_extensions/interlinks

docs/_quarto.yml

@@ -4,6 +4,17 @@ project:
   resources:
     - objects.json
 
+filters:
+  - "interlinks"
+
+interlinks:
+  sources:
+    quartodoc:
+      # TODO: how to have it be "site root"?
+      url: "/"
+      inv: null
+      fallback: objects.json
+
 website:
   title: "quartodoc"
   navbar:

docs/api/index.md

@@ -1,4 +1,4 @@
-# get_object {#sec-get_object}
+# get_object {#get_object}
 
 `get_object(module: str, object_name: str, parser: str = 'numpy')`
 
@@ -23,21 +23,21 @@ get_function: a deprecated function.
 <Function('get_function', ...
 ```
 
-# create_inventory {#sec-create_inventory}
+# create_inventory {#create_inventory}
 
-`create_inventory(project: str, version: str, items: list[dc.Object | dc.Alias], uri: str | Callable[dc.Object, str] = <function <lambda> at 0x105878700>, dispname: str | Callable[dc.Object, str] = '-')`
+`create_inventory(project: str, version: str, items: list[dc.Object | dc.Alias], uri: str | Callable[dc.Object, str] = lambda s: f'{s.canonical_path}.html', dispname: str | Callable[dc.Object, str] = '-')`
 
 Return a sphinx inventory file.
 
 ## Parameters
 
-| Name       | Type                           | Description                                                    | Default                              |
-|------------|--------------------------------|----------------------------------------------------------------|--------------------------------------|
-| `project`  | str                            | Name of the project (often the package name).                  | required                             |
-| `version`  | str                            | Version of the project (often the package version).            | required                             |
-| `items`    | list[dc.Object | dc.Alias]     | A docstring parser to use.                                     | required                             |
-| `uri`      | str | Callable[dc.Object, str] | Link relative to the docs where the items documentation lives. | `<function <lambda> at 0x105878700>` |
-| `dispname` | str | Callable[dc.Object, str] | Name to be shown when a link to the item is made.              | `'-'`                                |
+| Name       | Type                           | Description                                                    | Default                                |
+|------------|--------------------------------|----------------------------------------------------------------|----------------------------------------|
+| `project`  | str                            | Name of the project (often the package name).                  | required                               |
+| `version`  | str                            | Version of the project (often the package version).            | required                               |
+| `items`    | list[dc.Object | dc.Alias]     | A docstring parser to use.                                     | required                               |
+| `uri`      | str | Callable[dc.Object, str] | Link relative to the docs where the items documentation lives. | `lambda s: f'{s.canonical_path}.html'` |
+| `dispname` | str | Callable[dc.Object, str] | Name to be shown when a link to the item is made.              | `'-'`                                  |
 
 ## Examples
 
@@ -63,7 +63,7 @@ To preview the inventory, we can convert it to a dictionary:
    'dispname': '-'}]}
 ```
 
-# convert_inventory {#sec-convert_inventory}
+# convert_inventory {#convert_inventory}
 
 `convert_inventory(in_name: Union[str, soi.Inventory], out_name=None)`
 
@@ -76,7 +76,7 @@ Convert a sphinx inventory file to json.
 | `in_name`  | Union[str, soi.Inventory] | Name of inventory file. | required  |
 | `out_name` |                           | Output file name.       | `None`    |
 
-# MdRenderer {#sec-MdRenderer}
+# MdRenderer {#MdRenderer}
 
 `MdRenderer(self, header_level: int = 2, show_signature: bool = True, hook_pre=None)`
 

docs/get-started/crossrefs.qmd

@@ -9,6 +9,16 @@ 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` |
+
 ## Link within a doc
 
 * `@sec-get_object` doesn't seem to work: @sec-get-_object.

docs/objects.json

@@ -1 +1 @@
-{"project": "quartodoc", "version": "0.0.3.dev4+gb8c1275.d20221122", "count": 4, "items": [{"name": "quartodoc.get_object", "domain": "py", "role": "function", "priority": "1", "uri": "api/#get_object", "dispname": "get_object"}, {"name": "quartodoc.create_inventory", "domain": "py", "role": "function", "priority": "1", "uri": "api/#create_inventory", "dispname": "create_inventory"}, {"name": "quartodoc.convert_inventory", "domain": "py", "role": "function", "priority": "1", "uri": "api/#convert_inventory", "dispname": "convert_inventory"}, {"name": "quartodoc.MdRenderer", "domain": "py", "role": "class", "priority": "1", "uri": "api/#MdRenderer", "dispname": "MdRenderer"}]}
+{"project": "quartodoc", "version": "0.0.4.dev2+g7f17155", "count": 4, "items": [{"name": "quartodoc.get_object", "domain": "py", "role": "function", "priority": "1", "uri": "api/#get_object", "dispname": "get_object"}, {"name": "quartodoc.create_inventory", "domain": "py", "role": "function", "priority": "1", "uri": "api/#create_inventory", "dispname": "create_inventory"}, {"name": "quartodoc.convert_inventory", "domain": "py", "role": "function", "priority": "1", "uri": "api/#convert_inventory", "dispname": "convert_inventory"}, {"name": "quartodoc.MdRenderer", "domain": "py", "role": "class", "priority": "1", "uri": "api/#MdRenderer", "dispname": "MdRenderer"}]}