Merge pull request #1021 from DanielNoord/docs/autodoc

Use only ``autodoc`` to generate the API documentation

Author: Julian

.github/workflows/ci.yml

@@ -153,7 +153,7 @@ jobs:
     - name: Install dependencies
       run: >
         sudo apt-get update &&
-        sudo apt-get install -y libenchant-dev libxml2-dev libxslt-dev
+        sudo apt-get install -y libenchant-2-dev libxml2-dev libxslt-dev
       if: runner.os == 'Linux' && startsWith(matrix.python-version.toxenv, 'docs-')
     - name: Install dependencies
       run: brew install enchant

.pre-commit-config.yaml

@@ -5,7 +5,6 @@ repos:
     rev: v4.4.0
     hooks:
       - id: check-ast
-      - id: check-docstring-first
       - id: check-json
       - id: check-toml
       - id: check-vcs-permalinks

docs/api/index.rst

@@ -0,0 +1,22 @@
+API Reference
+=============
+
+Submodules
+----------
+
+.. toctree::
+   :titlesonly:
+
+   /api/jsonschema/validators/index
+   /api/jsonschema/exceptions/index
+   /api/jsonschema/protocols/index
+
+:mod:`jsonschema`
+-----------------
+
+.. automodule:: jsonschema
+   :members:
+   :imported-members:
+   :exclude-members: Validator
+
+.. autodata:: jsonschema._format._F

docs/api/jsonschema/exceptions/index.rst

@@ -0,0 +1,6 @@
+:py:mod:`jsonschema.exceptions`
+===============================
+
+.. automodule:: jsonschema.exceptions
+   :members:
+   :undoc-members:

docs/api/jsonschema/protocols/index.rst

@@ -0,0 +1,6 @@
+:py:mod:`jsonschema.protocols`
+==============================
+
+.. automodule:: jsonschema.protocols
+   :members:
+   :undoc-members:

docs/api/jsonschema/validators/index.rst

@@ -0,0 +1,6 @@
+:py:mod:`jsonschema.validators`
+===============================
+
+.. automodule:: jsonschema.validators
+   :members:
+   :undoc-members:

docs/conf.py

@@ -23,9 +23,6 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
-
-    "autoapi.extension",
-    "sphinx_autodoc_typehints",
     "sphinx_copybutton",
     "sphinx_json_schema_spec",
     "sphinxcontrib.spelling",
@@ -39,6 +36,33 @@
 
 html_theme = "furo"
 
+# See sphinx-doc/sphinx#10785
+_TYPE_ALIASES = {
+    "jsonschema._format._F",  # format checkers
+}
+
+
+def _resolve_type_aliases(app, env, node, contnode):
+    if (
+        node["refdomain"] == "py"
+        and node["reftype"] == "class"
+        and 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_type_aliases)
+
+
 # = Builders =
 
 doctest_global_setup = """

docs/validate.rst

@@ -58,6 +58,7 @@ versions.
 
 .. autoclass:: TypeChecker
     :members:
+    :noindex:
 
 .. autoexception:: jsonschema.exceptions.UndefinedTypeCheck
     :noindex:
@@ -88,7 +89,7 @@ given how common validating these types are.
 
 If you *do* want the generality, or just want to add a few specific additional
 types as being acceptable for a validator object, then you should update an
-existing `TypeChecker` or create a new one. You may then create a new
+existing `jsonschema.TypeChecker` or create a new one. You may then create a new
 `Validator` via `jsonschema.validators.extend`.
 
 .. testcode::
@@ -252,6 +253,7 @@ The supported mechanism for ensuring these dependencies are present is again as
 
 .. autoclass:: FormatChecker
     :members:
+    :noindex:
     :exclude-members: cls_checks
 
     .. attribute:: checkers

jsonschema/_format.py

@@ -11,6 +11,7 @@
 from jsonschema.exceptions import FormatError
 
 _FormatCheckCallable = typing.Callable[[object], bool]
+#: A format checker callable.
 _F = typing.TypeVar("_F", bound=_FormatCheckCallable)
 _RaisesType = typing.Union[
     typing.Type[Exception], typing.Tuple[typing.Type[Exception], ...],

jsonschema/exceptions.py

@@ -340,6 +340,15 @@ def relevance(error):
 
 
 relevance = by_relevance()
+"""
+A key function (e.g. to use with `sorted`) which sorts errors by relevance.
+
+Example:
+
+.. code:: python
+
+    sorted(validator.iter_errors(12), key=jsonschema.exceptions.relevance)
+"""
 
 
 def best_match(errors, key=relevance):