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

Question

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

这是 another module 的扩展我想将两者联系起来。我希望参数和返回类型作为链接使用。这是一个 example .

我的conf.py

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

这是一个链接了外部类的方法示例。外部类是 ModernGL.Context。我不确定是否必须配置记录此类的位置。但它应该指向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

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

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

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

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

:py:class:`ModernGL.Context`

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

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