如何使用 python sphinx link 到外部库？

Question

我在 RTD 上记录了一个 python 模块：http://modernglexttextools.readthedocs.io

这是 another module and I want to link between the two. I want the parameters and the return types to work as a link. Here is an example 的扩展。

我的conf.py

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.githubpages',
    'sphinx.ext.intersphinx',    # added this but does not help
    'sphinxcontrib.napoleon'
]

这是一个带有外部 class 链接的方法示例。外部class是ModernGL.Context。我不确定是否必须配置此 class 的记录位置。但它应该指向 this link.

def load(filename, convert=None, ctx=None) -> ModernGL.Texture:
    '''
        Load a texture. If ctx is ``None`` the default_context is used.

        Args:
            filename (str): The name of the file to load.

        Keyword Args:
            convert (str): Convert the texture before loading. Possible values are: ('L', 'RGB', 'RGBA')
            ctx (:py:class:`ModernGL.Context`): The Context to use for loading the texture.

        Returns:
            :py:class:`ModernGL.Texture`: The texture.

        Examples:

            .. code-block:: python

                import ModernGL
                from ModernGL.ext import textools

                ctx = ModernGL.create_standalone_context()
                # ctx = ModernGL.create_context()

                texture = textools.load('brick.jpg', ctx=ctx)
                texture.use()
    '''

Answer 1

如果我理解你的问题，听起来你只想将 link 从你的文档添加到他们的文档中，而不是将他们的文档包含在你的文档中。

将 Sphinx 扩展添加到 conf.py 中的 extensions 只是其用法的一部分。您还需要定义一个 intersphinx_mapping ，这是一个告诉扩展在哪里寻找外部文档的字典。例如：

# Looks for objects in external projects
intersphinx_mapping = {
    'moderngl': ('https://moderngl.readthedocs.io/en/stable/', None),
}

最后创建特定的 link，使用此语法：

:py:class:`ModernGL.Context`

此外，假设目标存在，link 可以使用以下语法完成对任意 targets 的操作：

:ref:`My Label <moderngl:MyArbitraryTarget>`

如何使用 python sphinx link 到外部库？

How to link to external libraries using python sphinx?

python

python-sphinx

python-moderngl