如何使用Sphinx和RST链接类似键入的嵌套类和其他url

Question

使用intersphinx和autodoc，具有：

:param stores: Array of objects
:type stores: list[dict[str,int]]

将导致输入类似：

• 商店 （[list [dict [str，int]]）-对象数组。

是否有使用原始RST（在文档字符串内）或以编程方式指定list[dict[str,int]]字符串将:param:转换为autodoc :rtype:派生词（或其他类似'list[dict[str,int]]'的方法）？

另外，是否可以在上述示例中使用外部链接？

示例

考虑script.py文件：

def some_func(arg1):
  """
  This is a head description.

  :param arg1: The type of this param is hyperlinked.
  :type arg1: list[dict[str,int]]

  Is it possible to hyperlink this, here: dict[str,list[int]]

  Or even add custom references amongst the classes: dict[int,ref]

  Where *ref* links to a foreign, external source.
  """ 

现在在Sphinx conf.py文件中添加：

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx'
]

intersphinx_mapping = {
  'py': ('https://docs.python.org/3', None),
}

在您的index.rst中，添加：

Title
=====

.. toctree::
  :maxdepth: 2

.. autofunction:: script.some_func

现在只需将页面的html make。

list[dict[str,int]]旁边的:type arg1:将超链接，如本问题开头所示，但dict[str,list[int]]显然不会。有没有办法使后者表现得像前者？

Answer 1

我深入研究了狮身人面像的代码后，找到了解决方案。

注入外部参考（：param：）

我创建了一个自定义扩展，该扩展连接到missing-reference事件并尝试解析未知引用。

reflinks.py的代码：

import docutils.nodes as nodes

_cache = {}

def fill_cache(app):
    _cache.update(app.config.reflinks)

def missing_reference(app, env, node, contnode):
    target = node['reftarget']
    try:
        uri = _cache[target]
    except KeyError:
        return
    newnode = nodes.reference('', '', internal = False, refuri = uri)
    if not node.get('refexplicit'):
        name = target.replace('_', ' ') # style
        contnode = contnode.__class__(name, name)
    newnode.append(contnode)
    return newnode

def setup(app):
    app.add_config_value(_host_attr, _host, False)
    app.connect('builder-inited', fill_cache)
    app.connect('missing-reference', missing_reference, priority = 1000)

说明

我咨询了intersphinx解决未知引用的方法，并以较高的优先级连接了该函数，因此希望仅作为最后结果进行咨询。

跟进

包括扩展名。

添加到conf.py：

reflinks = {'google': 'https://google.com'}

允许用于[[script.py：

def some_func(arg1):
    """
    :param arg1: Google homepages.
    :type arg1: dict[str, google]
    """

dict[str, google]现在都是超链接。
格式化嵌套类型
[在某些情况下，我想在list[dict[str,myref]]，:param:等字段之外使用:rtype:这样的类型结构。另一个简短的扩展就可以了。
nestlinks.py

的代码：

import sphinx.domains.python as domain
import docutils.parsers.rst.roles as roles

_field = domain.PyTypedField('class')

def handle(name, rawtext, text, lineno, inliner, options = {}, content = []):
    refs = _field.make_xrefs('class', 'py', text)
    return (refs, [])

def setup(app):
    roles.register_local_role('nref', handle)

说明
[阅读了this的角色指南，并深入研究here和here之后，我意识到我所需要的只是一个虚拟字段来处理整个参考制定工作，并假装好像在尝试引用类。
跟进
包括扩展名。
现在
script.py

：

def some_func(arg1):
    """
    :param arg1: Google homepages.
    :type arg1: dict[str, google]

    Now this :nref:`list[dict[str,google]]` is hyperlinked!
    """

注意
我正在使用intersphinx和autodoc链接到python的类型并记录我的函数的文档字符串。
我对Sphinx的基本机制并不精通，所以在方法论上要加点盐。
提供的示例经过调整，以使其可重复使用和通用，并且已经过[[not

进行了测试。

这些功能的可用性显然是有问题的，并且仅当诸如extlinks之类的库无法满足您的需求时才需要。