Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use only autodoc to generate the API documentation #1021

Merged
merged 9 commits into from Dec 2, 2022
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Expand Up @@ -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
Expand Down
1 change: 0 additions & 1 deletion .pre-commit-config.yaml
Expand Up @@ -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
Expand Down
22 changes: 22 additions & 0 deletions 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
6 changes: 6 additions & 0 deletions docs/api/jsonschema/exceptions/index.rst
@@ -0,0 +1,6 @@
:py:mod:`jsonschema.exceptions`
===============================

.. automodule:: jsonschema.exceptions
:members:
:undoc-members:
6 changes: 6 additions & 0 deletions docs/api/jsonschema/protocols/index.rst
@@ -0,0 +1,6 @@
:py:mod:`jsonschema.protocols`
==============================

.. automodule:: jsonschema.protocols
:members:
:undoc-members:
6 changes: 6 additions & 0 deletions docs/api/jsonschema/validators/index.rst
@@ -0,0 +1,6 @@
:py:mod:`jsonschema.validators`
===============================

.. automodule:: jsonschema.validators
:members:
:undoc-members:
30 changes: 27 additions & 3 deletions docs/conf.py
Expand Up @@ -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",
Expand All @@ -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 = """
Expand Down
4 changes: 3 additions & 1 deletion docs/validate.rst
Expand Up @@ -58,6 +58,7 @@ versions.

.. autoclass:: TypeChecker
:members:
:noindex:

.. autoexception:: jsonschema.exceptions.UndefinedTypeCheck
:noindex:
Expand Down Expand Up @@ -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::
Expand Down Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions jsonschema/_format.py
Expand Up @@ -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], ...],
Expand Down
9 changes: 9 additions & 0 deletions jsonschema/exceptions.py
Expand Up @@ -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):
Expand Down