如何使用python sphinx链接到外部库？

Question

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

这是另一个模块的扩展，我想在两者之间建立联系。我希望参数和返回类型作为链接工作。这是一个例子。

我的conf.py

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

以下是链接外部类的方法示例。外部类是ModernGL.Context. 我不确定是否必须配置此类的记录位置。但它应该指向这个链接。

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

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

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

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

最后要创建特定链接，请使用以下语法：

:py:class:`ModernGL.Context`

此外，假设目标存在，可以使用以下语法链接到任意目标：

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