From eda2dd2ccc68e351596ce2a8cfccbb1f308a7ef4 Mon Sep 17 00:00:00 2001 From: James Knight Date: Sun, 7 Apr 2024 12:32:12 -0400 Subject: [PATCH 1/2] [ext-linkcode] allow builders to flag support for linkcode references The original `sphinx.ext.linkcode` extension will only include references into a doctree for `html` builders. Custom builders who would like to handle linkcode references do not have a graceful way to enable this feature. This commit aims to allow custom builders to override when these references are included. If a builder defines a `supported_linkcode` attribute, this extension will use the value of this attribute to consider other builders/formats when conditionally adding references. Signed-off-by: James Knight --- sphinx/ext/linkcode.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/sphinx/ext/linkcode.py b/sphinx/ext/linkcode.py index 93118cd6745..63bd6ebd2c4 100644 --- a/sphinx/ext/linkcode.py +++ b/sphinx/ext/linkcode.py @@ -31,6 +31,12 @@ def doctree_read(app: Sphinx, doctree: Node) -> None: raise LinkcodeError(msg) assert resolve_target is not None # for mypy + # By default, the linkcode extension will only inject references + # for a `html` builder. If a builder wishes to support managing + # references generated by linkcode as well, it can define the + # `supported_linkcode` attribute. + node_only_expr = getattr(app.builder, 'supported_linkcode', 'html') + domain_keys = { 'py': ['module', 'fullname'], 'c': ['names'], @@ -67,7 +73,7 @@ def doctree_read(app: Sphinx, doctree: Node) -> None: uris.add(uri) inline = nodes.inline('', _('[source]'), classes=['viewcode-link']) - onlynode = addnodes.only(expr='html') + onlynode = addnodes.only(expr=node_only_expr) onlynode += nodes.reference('', '', inline, internal=False, refuri=uri) signode += onlynode From 905ea4fa567896bdfe8a784bab37c028d2179f8a Mon Sep 17 00:00:00 2001 From: James Knight Date: Sun, 7 Apr 2024 12:32:26 -0400 Subject: [PATCH 2/2] [doc] add extdev documentation for interfacing with the linkcode ext Adding a document under Sphinx's "extension development" chapter which provides information about integrating third-party builds with recently added features to the built-in linkcode extension. Signed-off-by: James Knight --- doc/extdev/extensions/index.rst | 15 +++++++++++++++ doc/extdev/extensions/linkcode.rst | 25 +++++++++++++++++++++++++ doc/extdev/index.rst | 1 + 3 files changed, 41 insertions(+) create mode 100644 doc/extdev/extensions/index.rst create mode 100644 doc/extdev/extensions/linkcode.rst diff --git a/doc/extdev/extensions/index.rst b/doc/extdev/extensions/index.rst new file mode 100644 index 00000000000..6e29177eb80 --- /dev/null +++ b/doc/extdev/extensions/index.rst @@ -0,0 +1,15 @@ +======================= +Built-in extensions API +======================= + +Sphinx includes several :ref:`built-in extensions `, +which third-party extensions may wish to integrate with. This chapter +describes the extensions bundled with Sphinx which provide an API which +other extensions may interface with. + +For the API documentation on writing your own extension, refer to +:ref:`dev-extensions`. + +.. toctree:: + + linkcode diff --git a/doc/extdev/extensions/linkcode.rst b/doc/extdev/extensions/linkcode.rst new file mode 100644 index 00000000000..7d56618f480 --- /dev/null +++ b/doc/extdev/extensions/linkcode.rst @@ -0,0 +1,25 @@ +``sphinx.ext.linkcode`` API +=========================== + +Refer to :mod:`sphinx.ext.linkcode` more for information about the +extension and its configuration. + +Builder API +----------- + +.. class:: MyAwesomeBuilder + + .. attribute:: supported_linkcode + + The linkcode extension will only inject references for an ``html`` + builder. If a builder wishes to support managing references + generated by linkcode, the ``supported_linkcode`` attribute can be + defined in the builder's implementation. + + For example: + + .. code-block:: python + + class MyAwesomeBuilder(Builder): + supported_linkcode = True + ... diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index 8332315ff93..307e82a98bc 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -215,4 +215,5 @@ disposal when developing Sphinx extensions. Some are core to Sphinx logging i18n utils + extensions/index deprecated