Trivial docs on writing schema packages.

Author: Julian

docs/conf.py

@@ -89,15 +89,22 @@ def setup(app):
 # -- Options for intersphinx extension ---------------------------------------
 
 intersphinx_mapping = {
+    "hatch": ("https://hatch.pypa.io/latest/", None),
+    "jsonschema-specifications": (
+        "https://jsonschema-specifications.readthedocs.io/en/latest/",
+        None,
+    ),
     "pyrsistent": ("https://pyrsistent.readthedocs.io/en/latest/", None),
     "python": ("https://docs.python.org/", None),
+    "setuptools": ("https://setuptools.pypa.io/en/latest/", None),
 }
 
 # -- Options for extlinks extension ------------------------------------------
 
 extlinks = {
     "gh": (str(HOMEPAGE) + "/%s", None),
     "github": (str(GITHUB) + "/%s", None),
+    "hatch": ("https://hatch.pypa.io/latest/%s", None),
 }
 
 # -- Options for the linkcheck builder ---------------------------------------

docs/index.rst

@@ -8,4 +8,5 @@ Contents
     :glob:
     :maxdepth: 2
 
+    schema-packages
     api

docs/schema-packages.rst

@@ -0,0 +1,15 @@
+===============
+Schema Packages
+===============
+
+The `Registry` object is a useful way to ship Python packages which essentially bundle a set of JSON Schemas for use at runtime from Python.
+
+In order to do so, you likely will want to:
+
+* Collect together the JSON files you wish to ship
+* Put them inside a Python package (one you possibly tag with the ``jsonschema`` keyword for easy discoverability).
+  Remember to ensure you have configured your build tool to include the JSON files in your built package distribution -- for e.g. :hatch:`hatch </>` this is likely automatic, but for `setuptools <setuptools:index>` may involve creating a suitable :file:`MANIFEST.in`.
+* Instantiate a `Registry` object somewhere globally within the package
+* Call `Registry.crawl` at import-time, such that users of your package get a "fully ready" registry to use
+
+For an example of such a package, see `jsonschema-specifications <jsonschema-specifications:index>`, which bundles the JSON Schema "official" schemas for use.

docs/spelling_wordlist.txt

@@ -1,7 +1,10 @@
 autodetecting
 deserialized
+discoverability
 referenceable
 resolvers
+runtime
+schemas
 submodules
 subresource
 subresources