Allow extensions to define the keys returned by linkcode ext

CHANGES.rst

@@ -19,6 +19,9 @@ Features added
 
 * #11701: HTML Search: Adopt the new `<search>`_ element.
   Patch by Bénédikt Tran.
+* #11824: linkcode: Allow extensions to add support for a domain by defining
+  the keys that should be present.
+  Patch by Nicolas Peugnet.
 
   .. _`<search>`: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/search
 

doc/extdev/appapi.rst

@@ -79,6 +79,8 @@ package.
 
 .. automethod:: Sphinx.add_autodoc_attrgetter
 
+.. automethod:: Sphinx.add_linkcode_domain
+
 .. automethod:: Sphinx.add_search_language
 
 .. automethod:: Sphinx.add_source_suffix

doc/usage/extensions/linkcode.rst

@@ -38,6 +38,9 @@ Configuration
    - ``javascript``: ``object`` (name of the object), ``fullname``
      (name of the item)
 
+   Support for other domains can be added with
+   :py:meth:`.Sphinx.add_linkcode_domain()`.
+
    Example:
 
    .. code-block:: python

sphinx/application.py

@@ -1178,6 +1178,15 @@ def add_autodoc_attrgetter(self, typ: type, getter: Callable[[Any, str, Any], An
         logger.debug('[app] adding autodoc attrgetter: %r', (typ, getter))
         self.registry.add_autodoc_attrgetter(typ, getter)
 
+    def add_linkcode_domain(self, domain: str, keys: list[str]) -> None:
+        """Register a new list of keys to use for a domain by the
+        :mod:`sphinx.ext.linkcode` extension.
+
+        .. versionadded:: 7.3
+        """
+        from sphinx.ext.linkcode import domain_keys
+        domain_keys[domain] = keys
+
     def add_search_language(self, cls: Any) -> None:
         """Register a new language for the HTML search index.
 

sphinx/ext/linkcode.py

@@ -17,6 +17,14 @@
     from sphinx.application import Sphinx
 
 
+domain_keys = {
+    'py': ['module', 'fullname'],
+    'c': ['names'],
+    'cpp': ['names'],
+    'js': ['object', 'fullname'],
+}
+
+
 class LinkcodeError(SphinxError):
     category = "linkcode error"
 
@@ -30,13 +38,6 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
         raise LinkcodeError(msg)
     assert resolve_target is not None  # for mypy
 
-    domain_keys = {
-        'py': ['module', 'fullname'],
-        'c': ['names'],
-        'cpp': ['names'],
-        'js': ['object', 'fullname'],
-    }
-
     for objnode in list(doctree.findall(addnodes.desc)):
         domain = objnode.get('domain')
         uris: set[str] = set()

tests/roots/test-ext-viewcode/conf.py

@@ -20,5 +20,10 @@ def linkcode_resolve(domain, info):
             return "http://foobar/js/" + info['fullname']
         elif domain in ("c", "cpp"):
             return f"http://foobar/{domain}/{''.join(info['names'])}"
+        elif domain == "rst":
+            return "http://foobar/rst/{fullname}".format(**info)
         else:
             raise AssertionError()
+
+    def setup(app):
+        app.add_linkcode_domain("rst", ["fullname"])

tests/roots/test-ext-viewcode/objects.rst

@@ -167,3 +167,10 @@ CPP domain
 
    .. cpp:function:: T& operator[]( unsigned j )
                      const T& operator[]( unsigned j ) const
+
+rST domain
+==========
+
+.. rst:role:: foo
+
+   Foo description.

tests/test_ext_viewcode.py

@@ -92,6 +92,7 @@ def test_linkcode(app, status, warning):
     assert 'http://foobar/js/' in stuff
     assert 'http://foobar/c/' in stuff
     assert 'http://foobar/cpp/' in stuff
+    assert 'http://foobar/rst/' in stuff
 
 
 @pytest.mark.sphinx(testroot='ext-viewcode-find', freshenv=True)