ext: allow builders to override support for linkcode references

[jdknight]

Feature or Bugfix

• Feature

Purpose

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.

Relates

• https://github.com/sphinx-contrib/confluencebuilder/issues/421

[jdknight]

It's much better to describe this behavior in the document of linkcode extension.

Just for clarity, are you asking that we add a comment inside the implementation to explain this option, such as:

@@ -24,6 +24,11 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
         raise LinkcodeError(
             "Function `linkcode_resolve` is not given in conf.py")

+    # By default, the linkcode extension will only inject references
+    # for an `html` builder/format. If a (third-party) builder wishes
+    # to support managing references generated by linkcode as well, they
+    # can override the `supported_linkcode` attribute in their builder
+    # definition.
     node_only_expr = getattr(app.builder, 'supported_linkcode', 'html')

     domain_keys = {

Or is there another document you are referring to? I assume it would not be doc/usage/extensions/linkcode.rst since that is more user focused. Unless you are recommending another document somewhere inside doc/extdev?

[AA-Turner]

Please may you add the new attribute/override mechanism somewhere in the documentation, and please also update CHANGES.

A

[jdknight]

@AA-Turner, any chance we can get this in a release window? If there is anything else that needed to be done, please let me know.

[kislyuk]

Hi all, is there anything that can be done to get this merged? I am looking to make use of @jdknight's excellent confluencebuilder extension, but I need it to work with linkcode and this looks to be the blocker.