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 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