Add extdev doc for interfacing with linkcode

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 <[email protected]>

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:`.MyAwesomeBuilder.supported_linkcode` attribute
+  for builders to enable use of :mod:`sphinx.ext.linkcode`-generated
+  references.
 
 Bugs fixed
 ----------

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,28 @@
+``sphinx.ext.linkcode`` API
+===========================
+
+Refer to :mod:`sphinx.ext.linkcode` for more information about the
+extension and its configuration.
+
+Builder API
+-----------
+
+.. class:: MyAwesomeBuilder
+
+   .. attribute:: supported_linkcode
+
+      The linkcode extension, by default, will only inject references
+      for an ``html`` builder. If a non-html builder wishes to support
+      managing references generated by linkcode, the
+      ``supported_linkcode`` attribute can be defined in the builder's
+      implementation. The expected value for this attribute is an
+      expression which is compatible with :rst:dir:`only`.
+
+      For example, if a builder was named ``my-awesome-builder``, the
+      following can be used:
+
+      .. code-block:: python
+
+         class MyAwesomeBuilder(Builder):
+             supported_linkcode = 'my-awesome-builder'
+             ...

doc/extdev/index.rst

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