Autodoc'ed (for now).

Also evade tobgu/pyrsistent#267 until it's merged.

Author: Julian

docs/api.rst

@@ -0,0 +1,30 @@
+API Reference
+=============
+
+.. automodule:: referencing
+   :members:
+   :undoc-members:
+   :imported-members:
+
+.. autoclass:: referencing._core.Resolver
+   :members:
+   :undoc-members:
+
+
+Submodules
+----------
+
+referencing.jsonschema
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: referencing.jsonschema
+   :members:
+   :undoc-members:
+
+
+referencing.typing
+^^^^^^^^^^^^^^^^^^
+
+.. automodule:: referencing.typing
+   :members:
+   :undoc-members:

docs/conf.py

@@ -3,6 +3,7 @@
 import re
 
 from hyperlink import URL
+from sphinx.ext.intersphinx import resolve_reference_in_inventory
 
 DOCS = Path(__file__).parent
 
@@ -40,6 +41,43 @@
 html_theme = "furo"
 html_static_path = []
 
+# See sphinx-doc/sphinx#10785
+_TYPE_ALIASES = {
+    "Schema",
+}
+
+
+def _resolve_broken_refs(app, env, node, contnode):
+    if node["refdomain"] != "py":
+        return
+
+    # Evade tobgu/pyrsistent#267
+    if node["reftarget"].startswith("pyrsistent.typing."):
+        node["reftarget"] = node["reftarget"].replace(".typing.", ".")
+        return resolve_reference_in_inventory(
+            env, "pyrsistent", node, contnode
+        )
+    elif node["reftarget"] == "PList":
+        node["reftarget"] = "pyrsistent.PList"
+        return resolve_reference_in_inventory(
+            env, "pyrsistent", node, contnode
+        )
+    elif node["reftarget"] in _TYPE_ALIASES:
+        return app.env.get_domain("py").resolve_xref(
+            env,
+            node["refdoc"],
+            app.builder,
+            "data",
+            node["reftarget"],
+            node,
+            contnode,
+        )
+
+
+def setup(app):
+    app.connect("missing-reference", _resolve_broken_refs)
+
+
 # -- Extension configuration -------------------------------------------------
 
 # -- Options for autodoc extension -------------------------------------------
@@ -56,6 +94,7 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 intersphinx_mapping = {
+    "pyrsistent": ("https://pyrsistent.readthedocs.io/en/latest/", None),
     "python": ("https://docs.python.org/", None),
 }
 

docs/index.rst

@@ -7,3 +7,5 @@ Contents
 .. toctree::
     :glob:
     :maxdepth: 2
+
+    api

referencing/typing.py

@@ -13,7 +13,10 @@
     from referencing._core import Resolver
 
 
+#: A JSON Schema which is a JSON object
 ObjectSchema = Mapping[str, Any]
+
+#: A JSON Schema of any kind
 Schema = Union[bool, ObjectSchema]