ext: allow builders to override support for linkcode references

doc/extdev/extensions/index.rst

@@ -0,0 +1,15 @@
+=======================
+Built-in extensions API
+=======================
+
+Sphinx includes several :ref:`built-in extensions <builtin-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

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

doc/extdev/index.rst

@@ -215,4 +215,5 @@ disposal when developing Sphinx extensions. Some are core to Sphinx
    logging
    i18n
    utils
+   extensions/index
    deprecated

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