validation: adding linkcode example

Adding an example of the linkcode extension into the validation set.

Signed-off-by: James Knight <[email protected]>

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