Merge pull request #989 from python-jsonschema/api

Enable dedicated API documentation page(s)

docs/conf.py

@@ -1,8 +1,12 @@
 from importlib import metadata
+from pathlib import Path
 import os
 import re
 import sys
 
+ROOT = Path(__file__).parent.parent
+PACKAGE_SRC = ROOT / "jsonschema"
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -25,6 +29,8 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+
+    "autoapi.extension",
     "sphinx_autodoc_typehints",
     "sphinx_json_schema_spec",
     "sphinxcontrib.spelling",
@@ -252,3 +258,27 @@ def entire_domain(host):
 # -- Options for sphinxcontrib-spelling -----------------------------------
 
 spelling_word_list_filename = "spelling-wordlist.txt"
+
+# -- Options for autoapi --------------------------------------------------
+
+suppress_warnings = [
+    "autoapi.python_import_resolution",
+    "autoapi.toc_reference",
+]
+autoapi_root = "api"
+autoapi_ignore = [
+    "*/_[a-z]*.py",
+    "*/__main__.py",
+    "*/benchmarks/*",
+    "*/cli.py",
+    "*/tests/*",
+]
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-module-summary",
+    "imported-members",
+]
+
+autoapi_type = "python"
+autoapi_dirs = [PACKAGE_SRC]

docs/creating.rst

@@ -7,12 +7,16 @@ Creating or Extending Validator Classes
 =======================================
 
 .. autofunction:: create
+    :noindex:
 
 .. autofunction:: extend
+    :noindex:
 
 .. autofunction:: validator_for
+    :noindex:
 
 .. autofunction:: validates
+    :noindex:
 
 
 Creating Validation Errors

docs/errors.rst

@@ -8,6 +8,7 @@ When an invalid instance is encountered, a `ValidationError` will be
 raised or returned, depending on which method or function is used.
 
 .. autoexception:: ValidationError
+    :noindex:
 
     The information carried by an error roughly breaks down into:
 
@@ -123,6 +124,7 @@ In case an invalid schema itself is encountered, a `SchemaError` is
 raised.
 
 .. autoexception:: SchemaError
+    :noindex:
 
     The same attributes are present as for `ValidationError`\s.
 
@@ -229,6 +231,7 @@ failed when validating a given instance, you may want to do so using
 `jsonschema.exceptions.ErrorTree` objects.
 
 .. autoclass:: jsonschema.exceptions.ErrorTree
+    :noindex:
     :members:
     :special-members:
     :exclude-members: __dict__,__weakref__
@@ -361,9 +364,11 @@ to guess the most relevant error in a given bunch.
 
 
 .. autofunction:: best_match
+    :noindex:
 
 
 .. function:: relevance(validation_error)
+    :noindex:
 
     A key function that sorts errors based on heuristic relevance.
 
@@ -403,3 +408,4 @@ to guess the most relevant error in a given bunch.
 
 
 .. autofunction:: by_relevance
+    :noindex:

docs/faq.rst

@@ -85,7 +85,7 @@ The JSON object ``{}`` is simply the Python `dict` ``{}``, and a JSON Schema lik
 
    The :kw:`$ref` keyword is a single notable exception.
 
-   Specifically, in the case where `jsonschema` is asked to `resolve a remote reference <RefResolver>`, it has no choice but to assume that the remote reference is serialized as JSON, and to deserialize it using the `json` module.
+   Specifically, in the case where `jsonschema` is asked to `resolve a remote reference <jsonschema.validators.RefResolver>`, it has no choice but to assume that the remote reference is serialized as JSON, and to deserialize it using the `json` module.
 
    One cannot today therefore reference some remote piece of YAML and have it deserialized into Python objects by this library without doing some additional work.
 
@@ -104,7 +104,7 @@ How do I configure a base URI for $ref resolution using local files?
 
 `jsonschema` supports loading schemas from the filesystem.
 
-The most common mistake when configuring a :class:`~jsonschema.RefResolver`
+The most common mistake when configuring a `jsonschema.validators.RefResolver`
 to retrieve schemas from the local filesystem is to give it a base URI
 which points to a directory, but forget to add a trailing slash.
 
@@ -212,8 +212,8 @@ be valid under the schema.)
 
 See the above-linked document for more info on how this works,
 but basically, it just extends the :kw:`properties` keyword on a
-`jsonschema.Draft202012Validator` to then go ahead and update all the
-defaults.
+`jsonschema.validators.Draft202012Validator` to then go ahead and update
+all the defaults.
 
 .. note::
 

docs/index.rst

@@ -1,4 +1,6 @@
 .. module:: jsonschema
+   :noindex:
+
 .. include:: ../README.rst
 
 
@@ -13,6 +15,7 @@ Contents
     references
     creating
     faq
+    api/index
 
 
 Indices and tables

docs/references.rst

@@ -6,8 +6,10 @@ Resolving JSON References
 .. currentmodule:: jsonschema
 
 .. autoclass:: RefResolver
+    :noindex:
     :members:
 
 .. autoexception:: RefResolutionError
+    :noindex:
 
     A JSON reference failed to resolve.

docs/requirements.in

@@ -2,6 +2,7 @@ file:.#egg=jsonschema
 furo
 lxml
 sphinx
+sphinx-autoapi
 sphinx-autodoc-typehints
 sphinx-json-schema-spec
 sphinxcontrib-spelling

docs/requirements.txt

@@ -6,6 +6,8 @@
 #
 alabaster==0.7.12
     # via sphinx
+astroid==2.12.2
+    # via sphinx-autoapi
 attrs==22.1.0
     # via jsonschema
 babel==2.10.3
@@ -25,9 +27,13 @@ idna==3.3
 imagesize==1.4.1
     # via sphinx
 jinja2==3.1.2
-    # via sphinx
+    # via
+    #   sphinx
+    #   sphinx-autoapi
 file:.#egg=jsonschema
     # via -r docs/requirements.in
+lazy-object-proxy==1.7.1
+    # via astroid
 lxml==4.9.1
     # via
     #   -r docs/requirements.in
@@ -48,6 +54,8 @@ pyrsistent==0.18.1
     # via jsonschema
 pytz==2022.2.1
     # via babel
+pyyaml==6.0
+    # via sphinx-autoapi
 requests==2.28.1
     # via sphinx
 snowballstemmer==2.2.0
@@ -58,10 +66,13 @@ sphinx==5.1.1
     # via
     #   -r docs/requirements.in
     #   furo
+    #   sphinx-autoapi
     #   sphinx-autodoc-typehints
     #   sphinx-basic-ng
     #   sphinx-json-schema-spec
     #   sphinxcontrib-spelling
+sphinx-autoapi==1.9.0
+    # via -r docs/requirements.in
 sphinx-autodoc-typehints==1.19.2
     # via -r docs/requirements.in
 sphinx-basic-ng==0.0.1a12
@@ -82,5 +93,9 @@ sphinxcontrib-serializinghtml==1.1.5
     # via sphinx
 sphinxcontrib-spelling==7.6.0
     # via -r docs/requirements.in
+unidecode==1.3.4
+    # via sphinx-autoapi
 urllib3==1.26.11
     # via requests
+wrapt==1.14.1
+    # via astroid

docs/spelling-wordlist.txt

@@ -7,6 +7,8 @@ ValidationError
 # 0th, sigh...
 th
 callables
+# non-codeblocked cls from autoapi
+cls
 deque
 dereferences
 deserialize
@@ -33,6 +35,8 @@ regex
 repr
 runtime
 sensical
+submodule
+submodules
 subschema
 subschemas
 subscopes

docs/validate.rst

@@ -13,6 +13,7 @@ The simplest way to validate an instance under a given schema is to use the
 :func:`validate` function.
 
 .. autofunction:: validate
+    :noindex:
 
 .. [#] For information on creating JSON schemas to validate
     your data, there is a good introduction to JSON Schema
@@ -28,6 +29,7 @@ The Validator Protocol
 to.
 
 .. autoclass:: jsonschema.protocols.Validator
+    :noindex:
     :members:
 
 All of the `versioned validators <versioned-validators>` that are included with
@@ -54,6 +56,7 @@ versions.
     :members:
 
 .. autoexception:: jsonschema.exceptions.UndefinedTypeCheck
+    :noindex:
 
     Raised when trying to remove a type check that is not known to this
     TypeChecker, or when calling `jsonschema.TypeChecker.is_type`
@@ -109,6 +112,7 @@ existing `TypeChecker` or create a new one. You may then create a new
 
 
 .. autoexception:: jsonschema.exceptions.UnknownType
+    :noindex:
 
 .. _versioned-validators:
 
@@ -121,16 +125,22 @@ that each validator class provides see the `Validator` protocol,
 which each included validator class implements.
 
 .. autoclass:: Draft202012Validator
+    :noindex:
 
 .. autoclass:: Draft201909Validator
+    :noindex:
 
 .. autoclass:: Draft7Validator
+    :noindex:
 
 .. autoclass:: Draft6Validator
+    :noindex:
 
 .. autoclass:: Draft4Validator
+    :noindex:
 
 .. autoclass:: Draft3Validator
+    :noindex:
 
 
 For example, if you wanted to validate a schema you created against the
@@ -181,7 +191,6 @@ validation can be enabled by hooking in a format-checking object into an
     :exclude-members: cls_checks
 
     .. attribute:: checkers
-
         A mapping of currently known formats to tuple of functions that
         validate them and errors that should be caught. New checkers can be
         added and removed either per-instance or globally for all checkers
@@ -204,6 +213,7 @@ validation can be enabled by hooking in a format-checking object into an
 
 
 .. autoexception:: FormatError
+    :noindex:
     :members:
 
 

jsonschema/__init__.py

@@ -4,8 +4,9 @@
 The main functionality is provided by the validator classes for each of the
 supported JSON Schema versions.
 
-Most commonly, `validate` is the quickest way to simply validate a given
-instance under a schema, and will create a validator for you.
+Most commonly, `jsonschema.validators.validate` is the quickest way to simply
+validate a given instance under a schema, and will create a validator
+for you.
 """
 import warnings
 

jsonschema/protocols.py

@@ -31,7 +31,6 @@
     import jsonschema
 
 from jsonschema.exceptions import ValidationError
-from jsonschema.validators import RefResolver
 
 # For code authors working on the validator protocol, these are the three
 # use-cases which should be kept in mind:
@@ -103,7 +102,7 @@ class Validator(Protocol):
     def __init__(
         self,
         schema: Mapping | bool,
-        resolver: RefResolver | None = None,
+        resolver: jsonschema.RefResolver | None = None,
         format_checker: jsonschema.FormatChecker | None = None,
     ) -> None:
         ...

jsonschema/validators.py

@@ -1045,10 +1045,11 @@ def validate(instance, schema, cls=None, *args, **kwargs):
     itself valid, since not doing so can lead to less obvious error
     messages and fail in less obvious or consistent ways.
 
-    If you know you have a valid schema already, especially if you
-    intend to validate multiple instances with the same schema, you
-    likely would prefer using the `Validator.validate` method directly
-    on a specific validator (e.g. ``Draft7Validator.validate``).
+    If you know you have a valid schema already, especially
+    if you intend to validate multiple instances with
+    the same schema, you likely would prefer using the
+    `jsonschema.protocols.Validator.validate` method directly on a
+    specific validator (e.g. ``Draft20212Validator.validate``).
 
 
     Arguments:
@@ -1061,7 +1062,7 @@ def validate(instance, schema, cls=None, *args, **kwargs):
 
             The schema to validate with
 
-        cls (Validator):
+        cls (jsonschema.protocols.Validator):
 
             The class that will be used to validate the instance.