From a9da9bc3035a7f84c4097a25afb52a1010f5b6d9 Mon Sep 17 00:00:00 2001 From: KB Sriram Date: Sat, 29 Jul 2023 18:11:48 -0700 Subject: [PATCH] docs: update sphinx conf.py to use cp_typing. - Adds circuitpython_typing to the intersphinx configuration. - Adds a workaround to resolve TypeAliased references. Fixes https://github.com/adafruit/circuitpython/issues/8119 --- conf.py | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/conf.py b/conf.py index e14c6ace83..645961c457 100644 --- a/conf.py +++ b/conf.py @@ -30,6 +30,7 @@ from collections import defaultdict from sphinx.transforms import SphinxTransform from docutils import nodes from sphinx import addnodes +from sphinx.ext import intersphinx tools_describe = str(pathlib.Path(__file__).parent / "tools/describe") @@ -441,7 +442,8 @@ texinfo_documents = [ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {"cpython": ('https://docs.python.org/3/', None), - "register": ('https://circuitpython.readthedocs.io/projects/register/en/latest/', None)} + "register": ('https://circuitpython.readthedocs.io/projects/register/en/latest/', None), + "typing": ('https://circuitpython.readthedocs.io/projects/adafruit-circuitpython-typing/en/latest/', None)} # Adapted from sphinxcontrib-redirects from sphinx.builders import html as builders @@ -483,6 +485,26 @@ def generate_redirects(app): with open(redirected_filename, 'w') as f: f.write(TEMPLATE % urllib.parse.quote(to_path, '#/')) +def adafruit_typing_workaround(app, env, node, contnode): + # Sphinx marks a requesting node that uses circuitpython-typing + # as looking for a "class" definition, but unfortunately + # Sphinx doesn't recognize TypeAlias based types usefully from + # the typing library. + # (see: https://github.com/sphinx-doc/sphinx/issues/8934) + # Instead, it categorizes these types as "data". + # (see: python -m sphinx.ext.intersphinx \ + # https://docs.circuitpython.org/projects/adafruit-circuitpython-typing/en/latest/objects.inv) + # This workaround traps missing references, checks if + # they are likely to be in the circuitpython_typing package, + # and changes the requesting type from "class" to "data" if + # needed, and re-tries the reference resolver. + ref = node.get("reftarget", None) + if ref and ref.startswith("circuitpython_typing."): + dtype = node.get("reftype", None) + if dtype != "data": + node.attributes.update({"reftype": "data"}) + return intersphinx.missing_reference(app, env, node, contnode) + class CoreModuleTransform(SphinxTransform): default_priority = 870 @@ -519,4 +541,5 @@ def setup(app): app.add_js_file("filter.js") app.add_config_value('redirects_file', 'redirects', 'env') app.connect('builder-inited', generate_redirects) + app.connect('missing-reference', adafruit_typing_workaround) app.add_transform(CoreModuleTransform)