Merge pull request #1044 from sphinx-contrib/linkcode-improvements

`sphinx.ext.linkcode` Improvements

doc/features.rst

@@ -174,10 +174,7 @@ Type                              Notes
 
                                   Confluence does not support the injection of
                                   JavaScript into a page in most scenarios.
-`sphinx.ext.linkcode`_            Unsupported.
-
-                                  This extension only supports injecting
-                                  references for the ``html`` builder.
+`sphinx.ext.linkcode`_            Supported (Sphinx v8.1+)
 `sphinx.ext.mathjax`_             Unsupported.
 
                                   Confluence does not support the injection of

sphinxcontrib/confluencebuilder/builder.py

@@ -53,7 +53,7 @@ class ConfluenceBuilder(Builder):
     name = 'confluence'
     format = 'confluence_storage'
     supported_image_types = SUPPORTED_IMAGE_TYPES
-    supported_linkcode = True
+    supported_linkcode = name
     supported_remote_images = True
 
     def __init__(self, app, env=None):

sphinxcontrib/confluencebuilder/singlebuilder.py

@@ -14,6 +14,7 @@
 
 class SingleConfluenceBuilder(ConfluenceBuilder):
     name = 'singleconfluence'
+    supported_linkcode = name
 
     def assemble_doctree(self):
         root_doc = self.config.root_doc

tests/sample-sets/linkcode/conf.py

@@ -0,0 +1,10 @@
+extensions = [
+    'sphinxcontrib.confluencebuilder',
+    'sphinx.ext.linkcode',
+]
+
+def linkcode_resolve(domain, info):
+    name = info.get('fullname', None)
+    if not name:
+        return None
+    return  f'https://example.org/src/{name}'

tests/sample-sets/linkcode/index.rst

@@ -0,0 +1,8 @@
+linkcode
+========
+
+.. module:: example
+
+.. class:: ExampleModule
+
+   This is an example.

tests/sample-sets/linkcode/tox.ini

@@ -0,0 +1,11 @@
+[tox]
+package_root={toxinidir}{/}..{/}..{/}..
+
+[testenv]
+commands =
+    {envpython} -m tests.test_sample {posargs}
+setenv =
+    PYTHONDONTWRITEBYTECODE=1
+    TOX_INI_DIR={toxinidir}
+passenv = *
+use_develop = true

tests/test_validation.py

@@ -35,6 +35,7 @@ def setUpClass(cls):
         space_key = os.getenv(SPACE_ENV_KEY, DEFAULT_TEST_SPACE)
         cls.config = prepare_conf()
         cls.config['extensions'].append('sphinx.ext.ifconfig')
+        cls.config['extensions'].append('sphinx.ext.linkcode')
         cls.config['confluence_api_token'] = os.getenv(AUTH_ENV_KEY)
         cls.config['confluence_full_width'] = False
         cls.config['confluence_page_generation_notice'] = True
@@ -59,6 +60,16 @@ def setUpClass(cls):
         cls.test_key = os.getenv(TESTKEY_ENV_KEY, DEFAULT_TEST_KEY)
         cls.test_version = os.getenv(TESTKEY_ENV_VERSION, DEFAULT_TEST_VERSION)
 
+        def linkcode_resolve(domain, info):
+            module = info.get('module', None)
+            if module != 'linkcode_example':
+                return None
+            name = info.get('fullname', None)
+            if not name:
+                return None
+            return f'https://example.org/src/{name}'
+        cls.config['linkcode_resolve'] = linkcode_resolve
+
         # overrides from user
         try:
             from validation_test_overrides import config_overrides

tests/validation-sets/extensions/index.rst

@@ -11,4 +11,5 @@ found inside the internal tree.
     autosummary
     graphviz
     inheritance_diagram
+    linkcode
     todo

tests/validation-sets/extensions/linkcode.rst

@@ -0,0 +1,43 @@
+sphinx.ext.linkcode
+===================
+
+.. hint::
+
+    This requires registering the ``sphinx.ext.linkcode`` extension in the
+    documentation's configuration file.
+
+This page shows an example of the linkcode_ extension's capabilities. A
+project configuration defines a ``linkcode_resolve`` function:
+
+.. code-block:: python
+
+    def linkcode_resolve(domain, info):
+        name = info.get('fullname', None)
+        if not name:
+            return None
+        return "https://example.org/src/%s" % name
+
+When documents include object descriptions such as the following, source
+links should be included:
+
+.. code-block:: none
+
+    .. class:: ExampleModule
+
+       This is an example.
+
+Output
+------
+
+The following shows an example of linkcode:
+
+.. module:: linkcode_example
+
+.. class:: ExampleModule
+
+   This is an example.
+
+
+.. references ------------------------------------------------------------------
+
+.. _linkcode: https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html