diff options
author | Julian Berman <Julian@GrayVines.com> | 2022-08-17 14:07:36 +0300 |
---|---|---|
committer | Julian Berman <Julian@GrayVines.com> | 2022-08-17 14:07:36 +0300 |
commit | 263d4ee47cf72eecc932684b3a4e4dd1c05cb8dd (patch) | |
tree | 6ab0426605cab8af5be525279e17dd260339f215 | |
parent | fdf94c71b3c60f31849ceab426cab0bc5b81bea7 (diff) | |
download | jsonschema-263d4ee47cf72eecc932684b3a4e4dd1c05cb8dd.tar.gz |
Use the now-separated out sphinx-json-schema-spec for docs.
-rw-r--r-- | docs/conf.py | 2 | ||||
-rw-r--r-- | docs/jsonschema_role.py | 153 | ||||
-rw-r--r-- | docs/requirements.in | 1 | ||||
-rw-r--r-- | docs/requirements.txt | 13 |
4 files changed, 11 insertions, 158 deletions
diff --git a/docs/conf.py b/docs/conf.py index f595f16..d419918 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -26,8 +26,8 @@ extensions = [ "sphinx.ext.napoleon", "sphinx.ext.viewcode", "sphinx_autodoc_typehints", + "sphinx_json_schema_spec", "sphinxcontrib.spelling", - "jsonschema_role", ] cache_path = "_cache" diff --git a/docs/jsonschema_role.py b/docs/jsonschema_role.py deleted file mode 100644 index c749fb4..0000000 --- a/docs/jsonschema_role.py +++ /dev/null @@ -1,153 +0,0 @@ -from contextlib import suppress -from datetime import datetime -from importlib import metadata -from pathlib import Path -from urllib.parse import urljoin -import urllib.request - -from docutils import nodes -from lxml import html -import certifi - -__version__ = "2.0.0" - -BASE_URL = "https://json-schema.org/draft/2020-12/" -VOCABULARIES = { - "core": urljoin(BASE_URL, "json-schema-core.html"), - "validation": urljoin(BASE_URL, "json-schema-validation.html"), -} -HARDCODED = { - "$ref": "https://json-schema.org/draft/2020-12/json-schema-core.html#ref", - "$schema": "https://json-schema.org/draft/2020-12/json-schema-core.html#name-the-schema-keyword", # noqa: E501 - "format": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-implementation-requirements", # noqa: E501 -} - - -def setup(app): - """ - Install the plugin. - - Arguments: - - app (sphinx.application.Sphinx): - - the Sphinx application context - """ - - app.add_config_value("cache_path", "_cache", "") - - CACHE = Path(app.config.cache_path) - CACHE.mkdir(exist_ok=True) - - documents = { - url: fetch_or_load(vocabulary_path=CACHE / f"{name}.html", url=url) - for name, url in VOCABULARIES.items() - } - app.add_role("kw", docutils_does_not_allow_using_classes(documents)) - - return dict(version=__version__, parallel_read_safe=True) - - -def fetch_or_load(vocabulary_path, url): - """ - Fetch a new specification or use the cache if it's current. - - Arguments: - - vocabulary_path: - - the local path to a cached vocabulary document - - url: - - the URL of the vocabulary document - """ - - headers = { - "User-Agent": "python-jsonschema v{} - documentation build v{}".format( - metadata.version("jsonschema"), - __version__, - ), - } - - with suppress(FileNotFoundError): - modified = datetime.utcfromtimestamp(vocabulary_path.stat().st_mtime) - date = modified.strftime("%a, %d %b %Y %I:%M:%S UTC") - headers["If-Modified-Since"] = date - - request = urllib.request.Request(url, headers=headers) - response = urllib.request.urlopen(request, cafile=certifi.where()) - - if response.code == 200: - with vocabulary_path.open("w+b") as spec: - spec.writelines(response) - spec.seek(0) - return html.parse(spec).getroot() - - return html.parse(vocabulary_path.read_bytes()).getroot() - - -def docutils_does_not_allow_using_classes(vocabularies): - """ - Yeah. - - It doesn't allow using a class because it does annoying stuff like - try to set attributes on the callable object rather than just - keeping a dict. - """ - - def keyword(name, raw_text, text, lineno, inliner): - """ - Link to the JSON Schema documentation for a keyword. - - Arguments: - - name (str): - - the name of the role in the document - - raw_source (str): - - the raw text (role with argument) - - text (str): - - the argument given to the role - - lineno (int): - - the line number - - inliner (docutils.parsers.rst.states.Inliner): - - the inliner - - Returns: - - tuple: - - a 2-tuple of nodes to insert into the document and an - iterable of system messages, both possibly empty - """ - - hardcoded = HARDCODED.get(text) - if hardcoded is not None: - return [nodes.reference(raw_text, text, refuri=hardcoded)], [] - - # find the header in the validation spec containing matching text - for vocabulary_url, spec in vocabularies.items(): - header = spec.get_element_by_id(f"name-{text.lower()}", None) - - if header is not None: - uri = urljoin(vocabulary_url, header.find("a").attrib["href"]) - break - else: - inliner.reporter.warning( - "Didn't find a target for {0}".format(text), - ) - uri = BASE_URL - - reference = nodes.reference(raw_text, text, refuri=uri) - return [reference], [] - - return keyword diff --git a/docs/requirements.in b/docs/requirements.in index 06623c0..f9ee77e 100644 --- a/docs/requirements.in +++ b/docs/requirements.in @@ -3,4 +3,5 @@ furo lxml sphinx sphinx-autodoc-typehints +sphinx-json-schema-spec sphinxcontrib-spelling diff --git a/docs/requirements.txt b/docs/requirements.txt index d35464c..f28c7d8 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -29,14 +29,16 @@ jinja2==3.1.2 file:.#egg=jsonschema # via -r docs/requirements.in lxml==4.9.1 - # via -r docs/requirements.in + # via + # -r docs/requirements.in + # sphinx-json-schema-spec markupsafe==2.1.1 # via jinja2 packaging==21.3 # via sphinx pyenchant==3.2.2 # via sphinxcontrib-spelling -pygments==2.12.0 +pygments==2.13.0 # via # furo # sphinx @@ -44,7 +46,7 @@ pyparsing==3.0.9 # via packaging pyrsistent==0.18.1 # via jsonschema -pytz==2022.1 +pytz==2022.2.1 # via babel requests==2.28.1 # via sphinx @@ -58,11 +60,14 @@ sphinx==5.1.1 # furo # sphinx-autodoc-typehints # sphinx-basic-ng + # sphinx-json-schema-spec # sphinxcontrib-spelling -sphinx-autodoc-typehints==1.19.0 +sphinx-autodoc-typehints==1.19.2 # via -r docs/requirements.in sphinx-basic-ng==0.0.1a12 # via furo +sphinx-json-schema-spec==2.2.2 + # via -r docs/requirements.in sphinxcontrib-applehelp==1.0.2 # via sphinx sphinxcontrib-devhelp==1.0.2 |