From b65fb168ec30baa90fb7f13e136f38c66b6c6b11 Mon Sep 17 00:00:00 2001
From: Andreas Motl <andreas.motl@panodata.org>
Date: Fri, 1 Mar 2024 12:51:03 +0100
Subject: [PATCH 1/3] Sphinx: Add inventory decoder for Sphinx

---
 pueblo/sphinx/__init__.py  |  0
 pueblo/sphinx/inventory.py | 40 ++++++++++++++++++++++++++++++++++++++
 pyproject.toml             |  5 ++++-
 3 files changed, 44 insertions(+), 1 deletion(-)
 create mode 100644 pueblo/sphinx/__init__.py
 create mode 100644 pueblo/sphinx/inventory.py

diff --git a/pueblo/sphinx/__init__.py b/pueblo/sphinx/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/pueblo/sphinx/inventory.py b/pueblo/sphinx/inventory.py
new file mode 100644
index 0000000..210018d
--- /dev/null
+++ b/pueblo/sphinx/inventory.py
@@ -0,0 +1,40 @@
+# ruff: noqa: T201
+from sphinx.ext.intersphinx import fetch_inventory, inspect_main
+
+
+class SphinxInventoryDecoder:
+    """
+    Decode and process intersphinx inventories created by Sphinx.
+
+    https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
+    """
+
+    def __init__(self, name: str, url: str):
+        self.name = name
+        self.url = url
+
+    def as_text(self):
+        inspect_main([self.url])
+
+    def as_markdown(self):
+        class MockConfig:
+            intersphinx_timeout: int | None = None
+            tls_verify = False
+            tls_cacerts: str | dict[str, str] | None = None
+            user_agent: str = ""
+
+        class MockApp:
+            srcdir = ""
+            config = MockConfig()
+
+        app = MockApp()
+        inv_data = fetch_inventory(app, "", self.url)
+        print(f"# {self.name}")
+        for key in sorted(inv_data or {}):
+            print(f"## {key}")
+            inv_entries = sorted(inv_data[key].items())
+            print("```text")
+            for entry, (_proj, _ver, url_path, display_name) in inv_entries:
+                display_name = display_name * (display_name != "-")
+                print(f"{entry: <40} {display_name: <40}: {url_path}")
+            print("```")
diff --git a/pyproject.toml b/pyproject.toml
index 3cc5a90..12bfabe 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -70,7 +70,7 @@ dependencies = [
 
 [project.optional-dependencies]
 all = [
-  "pueblo[cli,dataframe,fileio,nlp,notebook,proc,testing,web]",
+  "pueblo[cli,dataframe,fileio,nlp,notebook,proc,sphinx,testing,web]",
 ]
 cli = [
   "click<9",
@@ -117,6 +117,9 @@ release = [
   "build<2",
   "twine<6",
 ]
+sphinx = [
+  "sphinx",
+]
 test = [
   "pueblo[testing]",
 ]

From 704c5b95ccfb1410b7fc1d9d06d574c387571114 Mon Sep 17 00:00:00 2001
From: Andreas Motl <andreas.motl@panodata.org>
Date: Fri, 1 Mar 2024 13:15:35 +0100
Subject: [PATCH 2/3] Sphinx: Improve inventory decoder to optionally omit
 documents

---
 pueblo/sphinx/inventory.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/pueblo/sphinx/inventory.py b/pueblo/sphinx/inventory.py
index 210018d..b2f7ed6 100644
--- a/pueblo/sphinx/inventory.py
+++ b/pueblo/sphinx/inventory.py
@@ -16,7 +16,7 @@ def __init__(self, name: str, url: str):
     def as_text(self):
         inspect_main([self.url])
 
-    def as_markdown(self):
+    def as_markdown(self, omit_documents: bool = False):
         class MockConfig:
             intersphinx_timeout: int | None = None
             tls_verify = False
@@ -31,6 +31,8 @@ class MockApp:
         inv_data = fetch_inventory(app, "", self.url)
         print(f"# {self.name}")
         for key in sorted(inv_data or {}):
+            if omit_documents and key == "std:doc":
+                continue
             print(f"## {key}")
             inv_entries = sorted(inv_data[key].items())
             print("```text")

From 878a31f942bf69a9ec8439a0518b0f8e85dbdee0 Mon Sep 17 00:00:00 2001
From: Andreas Motl <andreas.motl@panodata.org>
Date: Fri, 1 Mar 2024 13:25:21 +0100
Subject: [PATCH 3/3] Sphinx: Improve inventory decoder to optionally use
 labels only

---
 pueblo/sphinx/inventory.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/pueblo/sphinx/inventory.py b/pueblo/sphinx/inventory.py
index b2f7ed6..7e4edd8 100644
--- a/pueblo/sphinx/inventory.py
+++ b/pueblo/sphinx/inventory.py
@@ -16,7 +16,7 @@ def __init__(self, name: str, url: str):
     def as_text(self):
         inspect_main([self.url])
 
-    def as_markdown(self, omit_documents: bool = False):
+    def as_markdown(self, omit_documents: bool = False, labels_only: bool = False):
         class MockConfig:
             intersphinx_timeout: int | None = None
             tls_verify = False
@@ -33,6 +33,8 @@ class MockApp:
         for key in sorted(inv_data or {}):
             if omit_documents and key == "std:doc":
                 continue
+            if labels_only and key != "std:label":
+                continue
             print(f"## {key}")
             inv_entries = sorted(inv_data[key].items())
             print("```text")