Allow builders to override support for linkcode references

[jdknight]

Note: this was originally proposed in #10585, but was accidentally removed during some cleanup; republishing.

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

• Can't see source code link when using linkcode sphinx-contrib/confluencebuilder#421
• ext: allow builders to override support for linkcode references #10585

[picnixz]

Some comments:

• I would expect supports_linkcode = True to indicate 'html'
• I would expect supports_linkcode = False to entirely disable linkcode support.
• I would recommend the documentation to explain that whatever is in supports_linkcode should match the only directive argument.

[jdknight]

I would recommend the documentation to explain that whatever is in supports_linkcode should match...

I would be happy to extend the documentation to be a bit more clear on what value should be used. The original submission would be that the value of this attribute is expected to have a compatible <expression> value that follows the only directive.

• I would expect supports_linkcode = True to indicate 'html'
• I would expect supports_linkcode = False to entirely disable linkcode support.

I am a bit confused on these statements. Setting supports_linkcode = False with the proposed change would disable linkcode support on any custom builder (in the same manner as if it was not set). And setting supports_linkcode = True would achieve the same results as if a builder specified supports_linkcode = 'html'.

 class MyAwesomeBuilder(Builder):
     supported_linkcode = True

... you would have an only node with True and not 'html'.

Is the ask here to instead of using an <expression> value, you want some sort of generator to create a custom only node?

[picnixz]

Setting supports_linkcode = False with the proposed change would disable linkcode support on any custom builder (in the same manner as if it was not set).

Is the ask here to instead of using an value, you want some sort of generator to create a custom only node?

Forget about my comment on them, I was mistaken.

I would be happy to extend the documentation to be a bit more clear on what value should be used. The original submission would be that the value of this attribute is expected to have a compatible

You can just say that whatever you use in supported_linkcode should match the expectations of the :rst:dir:`only` directive.

---

Also, you'll need a CHANGELOG entry!

[jdknight]

How about the following text?

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

For example, if a builder was named my-awesome-builder, the following can be used:

class MyAwesomeBuilder(Builder):
    supported_linkcode = 'my-awesome-builder'
    ...

(note: will format with proper rst/directives in the final change set)

[AA-Turner]

@jdknight I can't request a review from you as it's your PR -- please have a look at the pushed changes before merge.

A

[jdknight]

Changes look great; thanks!

[AA-Turner]

Thank you, James (@jdknight).

A

[picnixz]

I wasn't around for the review but the text is great! so thanks again!