Move to a function in the extension

doc/extdev/appapi.rst

@@ -79,8 +79,6 @@ 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

@@ -50,13 +50,20 @@ Configuration
           filename = info['module'].replace('.', '/')
           return "https://somesite/sourcerepo/%s.py" % filename
 
-   Support for other domains can be added by extensions with
-   :py:meth:`.Sphinx.add_linkcode_domain()`.
-   For example, a Sphinx extension that adds support for the ``php`` domain
-   could use the following code to add support for the ``php`` domain
-   in :mod:`~sphinx.ext.linkcode`:
 
-   .. code-block:: python
+Third-party domains
+-------------------
+
+Support for other domains can be added by extensions with
+:py:func:`.add_linkcode_domain()`.
+For example, a Sphinx extension that provides a ``php`` domain
+could use the following code to support :mod:`~sphinx.ext.linkcode`:
+
+.. code-block:: python
+
+   from sphinx.ext.linkcode import add_linkcode_domain
+
+   def setup(app):
+       add_linkcode_domain('php', ['namespace', 'class', 'fullname'])
 
-      def setup(app):
-          app.add_linkcode_domain('php', ['namespace', 'class', 'fullname'])
+.. autofunction:: add_linkcode_domain

sphinx/application.py

@@ -1531,15 +1531,6 @@ 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: type[SearchLanguage]) -> None:
         """Register a new language for the HTML search index.
 

sphinx/ext/linkcode.py

@@ -18,14 +18,23 @@
     from sphinx.util.typing import ExtensionMetadata
 
 
-domain_keys = {
+_DOMAIN_KEYS = {
     'py': ['module', 'fullname'],
     'c': ['names'],
     'cpp': ['names'],
     'js': ['object', 'fullname'],
 }
 
 
+def add_linkcode_domain(domain: str, keys: list[str], override: bool = False) -> None:
+    """Register a new list of keys to use for a domain.
+
+    .. versionadded:: 8.2
+    """
+    if override or domain not in _DOMAIN_KEYS:
+        _DOMAIN_KEYS[domain] = list(keys)
+
+
 class LinkcodeError(SphinxError):
     category = "linkcode error"
 
@@ -54,7 +63,7 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
 
             # Convert signode to a specified format
             info = {}
-            for key in domain_keys.get(domain, []):
+            for key in _DOMAIN_KEYS.get(domain, []):
                 value = signode.get(key)
                 if not value:
                     value = ''

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

@@ -1,6 +1,8 @@
 import sys
 from pathlib import Path
 
+from sphinx.ext.linkcode import add_linkcode_domain
+
 sys.path.insert(0, str(Path.cwd().resolve()))
 
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
@@ -25,4 +27,4 @@ def linkcode_resolve(domain, info):
             raise AssertionError()
 
     def setup(app):
-        app.add_linkcode_domain("rst", ["fullname"])
+        add_linkcode_domain("rst", ["fullname"])