Skip to content

Use only autodoc to generate the API documentation #1021

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’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Dec 2, 2022
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
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
Original file line number Diff line number Diff line change
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
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
:py:mod:`jsonschema.validators`
===============================

.. automodule:: jsonschema.validators
:members:
:undoc-members:
30 changes: 27 additions & 3 deletions docs/conf.py
Original file line number Diff line number Diff line change
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
Original file line number Diff line number Diff line change
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
Original file line number Diff line number Diff line change
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
Original file line number Diff line number Diff line change
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