Merge pull request #350 from machow/fix-interlinks-cross-site

docs: use fast interlinks

Author: machow

docs/_quarto.yml

@@ -5,6 +5,8 @@ project:
     - examples/single-page
     - examples/pkgdown
     - examples/auto-package
+    - objects.txt
+    - objects-test.txt
 
 metadata-files:
   - api/_sidebar.yml
@@ -13,11 +15,16 @@ filters:
   - "interlinks"
 
 interlinks:
+  fast: true
   sources:
     python:
       url: https://docs.python.org/3/
     griffe:
       url: https://mkdocstrings.github.io/griffe/
+    qd2:
+      url: https://pr-350--quartodoc.netlify.app/
+      inv: objects-test.txt
+
 
 website:
   title: "quartodoc"

docs/get-started/interlinks.qmd

@@ -43,17 +43,22 @@ interlinks:
       url: https://numpy.org/doc/stable/
     python:
       url: https://docs.python.org/3/
+    quartodoc-test:
+      url: https://machow.github.io/quartodoc
+      inv: objects-test.txt
 ```
 
 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 `inv` field lets you specify the name of the inventory file. By default, it assumes its `objects.inv`.
 
 By default, downloaded inventory files will be saved in the `_inv` folder of your
 documentation directory.
 
+
 ### Experimental fast option
 
 Use the experimental `fast: true` option to speed up the interlinks filter.
@@ -175,6 +180,9 @@ Most sphinx sites name them `object.inv`:
 See the [sphobjinv docs](https://sphobjinv.readthedocs.io/en/stable/) for thorough
 details on these files, and how they're used in sphinx.
 
+:::{.callout-note}
+[objects-test.txt](https://github.com/machow/quartodoc/tree/main/docs/objects-test.txt) is an example file with one entry: [](`qd2.Auto`).
+:::
 
 ## More information
 

docs/objects-test.txt

@@ -0,0 +1,5 @@
+# Sphinx inventory version 2
+# Project: quartodoc
+# Version: 0.0.9999
+# The remainder of this file is compressed using zlib.
+qd2.Auto py:class 1 api/Auto.html#quartodoc.Auto -

quartodoc/__main__.py

@@ -12,6 +12,7 @@
 from watchdog.events import PatternMatchingEventHandler
 from quartodoc import Builder, convert_inventory
 from ._pydantic_compat import BaseModel
+from .interlinks import inventory_from_url
 
 
 def get_package_path(package_name):
@@ -258,7 +259,8 @@ def interlinks(config, dry_run, fast):
             continue
 
         url = v["url"] + v.get("inv", "objects.inv")
-        inv = soi.Inventory(url=url)
+
+        inv = inventory_from_url(url)
 
         p_dst = p_root / cache / f"{k}_objects"
         p_dst.parent.mkdir(exist_ok=True, parents=True)

quartodoc/interlinks.py

@@ -9,12 +9,13 @@
 loaded specification.
 """
 
-
 from __future__ import annotations
 
 import os
 import itertools
 import json
+import requests
+import sphobjinv
 import warnings
 import yaml
 
@@ -38,6 +39,35 @@ class InvLookupError(Exception):
     """An error looking up an entry from inventory files."""
 
 
+# Save inventories from url ---------------------------------------------------
+# Note that this is the one piece used by quartodoc (whereas everything else
+# in this module is a model of the lua filter behavior).
+
+
+def inventory_from_url(url: str) -> sphobjinv.Inventory:
+    """Return an inventory file by fetching from a url.
+
+    Use the prefix file:// to load the file from disk.
+    """
+
+    if url.startswith("file://"):
+        with open(url.replace("file://", "", 1), "rb") as f:
+            raw_content = f.read()
+    else:
+        r = requests.get(url)
+        r.raise_for_status()
+        raw_content = r.content
+
+    if url.endswith(".inv"):
+        inv = sphobjinv.Inventory(zlib=raw_content)
+    elif url.endswith(".txt"):
+        inv = sphobjinv.Inventory(plaintext=raw_content)
+    else:
+        raise NotImplementedError("Inventories must be .txt or .inv files.")
+
+    return inv
+
+
 # Utility functions -----------------------------------------------------------
 
 

quartodoc/tests/test_interlinks.py

@@ -1,4 +1,5 @@
 import contextlib
+import sphobjinv
 import pytest
 import yaml
 
@@ -10,6 +11,7 @@
     TestSpecEntry,
     parse_md_style_link,
     Link,
+    inventory_from_url,
 )
 from importlib_resources import files
 
@@ -90,3 +92,26 @@ def test_spec_entry(invs: Inventories, entry: TestSpecEntry):
             assert entry.output_text == el.content
     elif entry.output_element:
         assert el == entry.output_element
+
+
+def test_inventory_from_url_local_roundtrip(tmp_path):
+    inv = sphobjinv.Inventory()
+    inv.project = "abc"
+    inv.version = "0.0.1"
+
+    soi_items = [
+        sphobjinv.DataObjStr(
+            name="foo", domain="py", role="method", priority="1", uri="$", dispname="-"
+        )
+    ]
+    inv.objects.extend(soi_items)
+
+    text = inv.data_file()
+    sphobjinv.writebytes(tmp_path / "objects.txt", text)
+    sphobjinv.writebytes(tmp_path / "objects.inv", sphobjinv.compress(text))
+
+    res1 = inventory_from_url("file://" + str(tmp_path / "objects.txt"))
+    res2 = inventory_from_url("file://" + str(tmp_path / "objects.inv"))
+
+    assert isinstance(res1, sphobjinv.Inventory)
+    assert isinstance(res2, sphobjinv.Inventory)