Allow builders to override support for linkcode references (#12852)

Signed-off-by: James Knight <james.d.knight@live.com>
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>

CHANGES.rst

@@ -66,6 +66,9 @@ Features added
   Patch by Hugo van Kemenade.
 * #11809: Improve the formatting for RFC section anchors.
   Patch by Jakub Stasiak and Adam Turner.
+* #12852: Support a :attr:`.Builder.supported_linkcode` attribute
+  for builders to enable use of :mod:`sphinx.ext.linkcode`-generated
+  references.
 
 Bugs fixed
 ----------

doc/extdev/builderapi.rst

@@ -64,3 +64,25 @@ Builder API
    .. attribute:: events
 
       An :class:`.EventManager` object.
+
+   .. rubric:: Overridable Attributes (extensions)
+
+   Builder sub-classes can set these attributes to support built-in extensions:
+
+   .. attribute:: supported_linkcode
+
+      By default, the :mod:`linkcode <sphinx.ext.linkcode>` extension will
+      only inject references for an ``html`` builder.
+      The ``supported_linkcode`` attribute can be defined in a non-HTML builder
+      to support managing references generated by linkcode.
+      The expected value for this attribute is an expression
+      which is compatible with :rst:dir:`only`.
+
+      For example, if a builder was named ``custom-builder``,
+      the following can be used:
+
+      .. code-block:: python
+
+         class CustomBuilder(Builder):
+             supported_linkcode = 'custom-builder'
+             ...

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