允许在Sphinx函数/方法描述中创建可链接的参数链接
项目描述
这是一个Sphinx扩展，允许Python文档中的:param:指令可链接。
这是SQLAlchemy项目及相关项目使用的实验性扩展。
配置
只需在conf.py中开启即可
extensions = [
'sphinx_paramlinks',
# your other sphinx extensions
# ...
]
从版本0.5.3开始，您可以通过在conf.py中使用paramlinks_hyperlink_param设置来修改可点击超链接在参数名称周围的位置
paramlinks_hyperlink_param='name'
此参数接受以下值
'none': 不会插入链接。参数仍然有目标链接，例如可以从搜索中跳转到它。
'name': 参数名称是一个可点击的超链接。
'link_symbol': 在参数名称之后（但在类型说明之前）插入一个可点击的链接符号。默认情况下，此符号仅当鼠标悬停于参数描述时才显示（见下文）
'name_and_symbol': 链接名称并生成链接符号。
默认为paramlinks_hyperlink_param = 'link_symbol'。
功能
:param: Sphinx 函数/方法描述中的指令将在段落链接中给出，以便它们可以外部链接。
新增了文本角色 :paramref:，它的工作方式类似于 :meth:、:func: 等。只需将参数名称作为额外标记附加即可。
:paramref:`.EnvironmentContext.configure.transactional_ddl`
该指令利用现有的 Python 角色进行方法/函数查找，首先搜索 :meth:，然后是 :class:，接着是 :func: 角色然后单独应用参数名称以生成最终的参考链接。（0.3.4 新增，分别搜索 :meth: / :func: / :class:，而不是使用 :obj:，后者会捕获许多没有参数的内容）
paramlinks 还被添加到主索引以及域对象列表中，这使得它们可以通过 searchindex.js 系统进行搜索。（0.3.0 新增）
样式表
段落链接涉及一个简短的样式表，以便在悬停时可见。此表单称为 sphinx_paramlinks.css，插件会自动将其复制到输出目录的 _static 目录。该样式表通过 Sphinx.add_stylesheet() 钩子添加到模板命名空间中存在的 css_files 列表。
自定义
要自定义链接样式，您可以通过添加自定义样式表来覆盖 sphinx_paramlinks.css 的配置
app.add_css_file("path/to/custom.css")
如果参数名称是超链接，HTML 代码将类似于以下内容
<a class="paramname reference internal" href="#package.method.params.parameter_name">
<strong>parameter_name</strong>
</a>
类 paramname 由 sphinx-paramlinks 定义，可以用于自定义样式。
如果在超链接后插入链接符号，HTML 代码将类似于以下内容
<a class="paramlink headerlink reference internal" href="#package.method.params.parameter_name">¶</a>
类 paramlink 由 sphinx-paramlinks 定义，可以用于自定义样式。
兼容性
Python 兼容性
sphinx-paramlinks 完全兼容 Python 3。
Sphinx 兼容性
我尽量减少了对 Sphinx 的假设，并只使用非常简单的公共 API，以便未来的 Sphinx 版本中的架构变化不会破坏此插件。为了创建此插件，我在 Sphinx 源代码中花费了数小时，并尝试了许多不同的方法来实现功能的不同方面；希望这里的内容尽可能简单和稳定，基于 Sphinx 当前扩展能力的当前扩展。
涉及使用一些内部元素的一个元素是使用 sphinx.domains.python.PyXRefRole 类，这是目前定义诸如 :meth:、:func: 等角色的 Sphinx 类。对象按原样使用，以定义 :paramref: 角色该角色产生的产品随后通过标准钩子进行转换。
另一个假设是为了定位 Sphinx 为 :param: 标签创建的 RST 节点，我们查看 nodes.strong，假设这是当前用于在 RST 中渲染 :param: 的节点类型。如果这发生变化，或者需要扩展以支持其他域，则可以根据需要打开此遍历。这部分很困难，因为 Sphinx 真的没有提供任何钩子来处理域的“信息字段列表”方面。
总体而言，这里的做法是将额外信息应用于进入Sphinx系统的结构，然后当数据返回时进行一些转换。这尽可能减少了对Sphinx如何执行其操作的依赖，而不是使用自定义域和大量注入API，这些API可能会在未来的版本中更改。
sphinx-paramlinks-0.6.0.tar.gz的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 746a0816860aa3fff5d8d746efcbec4deead421f152687411db1d613d29f915e |
|
| MD5 | 74a1cc657c1ef7015f137bcdf3d30a16 |
|
| BLAKE2b-256 | ae2162d3a58ff7bd02bbb9245a63d1f0d2e0455522a11a78951d16088569fca8 |