mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
75 lines
2.3 KiB
ReStructuredText
75 lines
2.3 KiB
ReStructuredText
:mod:`sphinx.ext.linkcode` -- Add external links to source code
|
|
===============================================================
|
|
|
|
.. module:: sphinx.ext.linkcode
|
|
:synopsis: Add external links to source code.
|
|
.. moduleauthor:: Pauli Virtanen
|
|
|
|
.. versionadded:: 1.2
|
|
|
|
.. role:: code-py(code)
|
|
:language: Python
|
|
|
|
This extension looks at your object descriptions (``.. class::``,
|
|
``.. function::`` etc.) and adds external links to code hosted
|
|
somewhere on the web. The intent is similar to the
|
|
``sphinx.ext.viewcode`` extension, but assumes the source code can be
|
|
found somewhere on the Internet.
|
|
|
|
In your configuration, you need to specify a :confval:`linkcode_resolve`
|
|
function that returns an URL based on the object.
|
|
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
.. confval:: linkcode_resolve
|
|
:type: :code-py:`Callable[[str, dict[str, str]], str | None] | None`
|
|
:default: :code-py:`None`
|
|
|
|
This is a function ``linkcode_resolve(domain, info)``,
|
|
which should return the URL to source code corresponding to
|
|
the object in given domain with given information.
|
|
|
|
The function should return ``None`` if no link is to be added.
|
|
|
|
The argument ``domain`` specifies the language domain the object is
|
|
in. ``info`` is a dictionary with the following keys guaranteed to
|
|
be present (dependent on the domain):
|
|
|
|
- ``py``: ``module`` (name of the module), ``fullname`` (name of the object)
|
|
- ``c``: ``names`` (list of names for the object)
|
|
- ``cpp``: ``names`` (list of names for the object)
|
|
- ``javascript``: ``object`` (name of the object), ``fullname``
|
|
(name of the item)
|
|
|
|
Example:
|
|
|
|
.. code-block:: python
|
|
|
|
def linkcode_resolve(domain, info):
|
|
if domain != 'py':
|
|
return None
|
|
if not info['module']:
|
|
return None
|
|
filename = info['module'].replace('.', '/')
|
|
return "https://somesite/sourcerepo/%s.py" % filename
|
|
|
|
|
|
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'])
|
|
|
|
.. autofunction:: add_linkcode_domain
|