SphinxRefmate

“一种辅助 reStructuredText 中 Sphinx 文档项目创建的引用工具包。”

关于

SphinxRefmate 是一个设计用于减少开发 Sphinx 文档项目时麻烦的引文管理器插件。该插件可以收集 Sphinx 项目中的各种参考类型，并按需以 Sublime Text 快速面板的形式呈现给用户。此菜单可以进行模糊搜索，以便用户能够轻松地找到和点击引用。这将然后在当前文档中正确位置插入正确的 reStructuredText 片段，例如指向所需引用的引用引用。

支持的引用类型

以下引用类型可以从当前活动的 Sphinx 文档项目中检索

• 参考文献引用（reST [作者_1966]_）
• 替换（reST |替代|）

以下引用类型可以从本地 Sphinx 文档项目中检索，并且可以从活动 intersphinx_mapping 变量中识别的任何关联 Sphinx 文档项目中检索

• 章节标签/引用（reST :ref:）
• 页面引用（reST :doc:）
• 术语（reST :term:）

节省时间和脑力劳动

例如，如果您正在编辑Sphinx Docs Web项目的重构文本页面，并想插入指向您几周前创建的关于“伦敦公交”的页面的超链接——但是您不记得其参考名称——使用Sphinx Refmate，您可以简单地在Tools -> Sphinx Refmate菜单下点击Insert Links To Current Project条目（或通过其他方法访问此命令，例如用户定义的快捷键），将会弹出一个快速面板列表，包括当前Sphinx项目中的所有文档（页面）链接。您可以在快速面板的选择标题中开始键入'伦敦 Bu..'，在过滤的过程中，您所需的精确'doc'风格链接将变得可见，您可以通过点击它来插入格式良好的reST链接。（注意：Sublime Text的常规菜单以及可配置的快捷键适用于所有Sphinx Refmate命令。）

安装

安装应使用Sublime Package Manager进行。

• Ctrl+Shift+P或Cmd+Shift+P在Linux/Windows/OS X上
• 键入install，选择Package Control: Install Package
• 键入sphinx，选择SphinxRefmate

也可以直接从SphinxRefmate的github仓库克隆到您的Sublime Text 包目录中。

使用

通过快捷键或菜单打开命令面板：Tools -> Command Palette并键入Sphinx Refmate可显示所有命令。

– 或 –

使用右键上下文菜单（默认情况下，仅在处于text.restructuredtext作用域时可用）。右键点击将通过Sphinx Refmate -> 各种子菜单显示各种选择。

注意：根据需要，可以通过插件设置（见下文）完全禁用或使上下文菜单独立。

– 或 –

使用Sublime Text的主菜单栏：Tools -> Sphinx Refmate -> 各种子菜单

设置

可以通过Preferences -> Package Settings -> Sphinx Refmate -> Settings编辑插件设置。以下是所有可用的SphinxRefmate设置及其对插件功能的影响列表。

“sphinx_check”：true

此设置确定是否在运行插件功能之前，Sphinx Refmate会检查它是否正在Sphinx Doc项目中运行（检查顶级文件夹conf.py）。设置为false以在任何环境中运行。

“enable_context_menu”：true

当此设置为true时，如果处于重构文本作用域（作用域）或所有作用域（如果rst_check设置为false），则'右键点击'上下文菜单将显示Sphinx Refmate菜单。要将Sphinx Refmate上下文菜单完全禁用，请将enable_context_menu设置为false。

“rst_check”：true

此设置确定在运行插件功能之前，Sphinx Refmate是否会检查编辑光标是否处于重构文本（作用域）中。设置为false以在任何作用域中运行。

“priv_project_prefix”： “priv”

Sphinx Refmate使用一个'intersphinx_mapping'变量（见下文），在其中的Sphinx Doc项目通过短名称键定义。如果此名称键以priv_前的priv_project_prefix开头（默认为'priv'），则Sphinx Refmate将认为此项目是私有的，而不是公有的，例如基于本地lan的html网站而不是基于互联网。对于Sphinx Refmate来说，区分私有和公有项目很重要，因为当编辑公有网站时，不应提供指向私有网站的不可到达链接。

“intersphinx_map_source_list”： [“filename1.py”， “filename2.py”]

**) SphinxRefmate 通过解析名为 objects.inv 的 Sphinx 文档数据库文件来定位 reST 中的 :ref:、:doc: 和 :term: 风格的引用。该文件通常位于 Sphinx 文档构建树的根目录中，是 Sphinx 项目构建过程的一个关键特性。Sphinx Refmate 通过 intersphinx_mapping 字典来理解如何查找特定项目的 objects.inv 文件，该字典通常定义在 Sphinx 文档项目的 conf.py 文件中。使用 intersphinx_map_source_list 来提供可能找到必要 intersphinx_mapping 变量的文件位置列表。Sphinx Refmate 将依次解析这些文件，并使用找到的第一个 intersphinx_mapping 变量来定位其中定义的一个或多个项目中的 objects.inv 文件。找到 objects.inv 文件后，Sphinx Refmate 会解析它以构建一个引用列表。这是一个特定 Sphinx 文档项目的引用列表，Sphinx Refmate 可以使用该列表，单独或与其他此类列表一起，来填充快速面板。

注意：intersphinx_mapping 变量通常与 Sphinx Doc Intersphinx 扩展相关联，其主要功能是将多个 Sphinx 文档项目名称（实际上是一些简短的别名）映射到它们对象文件的位置路径，以便 Intersphinx 能够在构建时管理多个项目的交叉引用。Sphinx Refmate Sublime Text 插件就使用这个 intersphinx_mapping 变量来使在设计时管理多个项目的交叉引用变得更加容易。要在多个项目中成功使用 SphinxRefmate，您需要对 intersphinx_mapping 变量的设计有一定的了解。如有必要，请参阅下面的 intersphinx_mapping 变量部分。

“bib_ref_file_list” : [“filename1.rst”, “filename2.rst”]

当被要求执行时，SphinxRefmate 将依次扫描 bib_ref_file_list 列表中的所有文件，以编译一系列 reStructuredText 引用。所寻找的引用是标准 reStructuredText 类型，更多详情请参考 docutils reST/citations。请注意，此功能旨在仅在单个项目中运行，这与 Sphinx 处理 reST 引用的项目内方式一致，请参阅 Sphinx 文档引用。

“rst_epilog_source_list” : [“filename1.py”, “filename2.py”]

当被要求执行时，SphinxRefmate 将依次扫描 rst_epilog_source_list 列表中的所有文件，以编译一个从所有 rst_epilog = 或 rst_epilog += 赋值语句中定义的 reStructuredText 替换列表。这些文件应该是 Python 源代码文件，您可能只需要定义一个 - 标准的 Sphinx 文档配置文件：conf.py。在发现的任何 rst_epilog 变量中寻找的是根据 reStructuredText 标准定义的替换，更多详情请参考 docutils reST/substitutions。请注意，此功能旨在仅在单个项目中运行，这与 Sphinx Docs 处理 reST 替换的项目内方式一致。另外，Sphinx Docs 的 rst_prolog 变量目前还不被解析（如果这些变量是项目中 reST 替换的来源，那么您需要将它们转移到 rst_epilog 变量）。有关 Sphinx rst_epilog 和 rst_prolog 变量的更多信息，请参阅 Sphinx 配置文档

项目插件设置

如果有需要，可以使用以下方式覆盖 SphinxRefmate 的所有文件列表设置，在项目的 sublime-project 文件中的 'settings' 部分添加如下条目：

"SphinxRefmate": { 
    "intersphinx_map_source_list": [ "/strangely/located/conf.py" ],
    "bib_ref_file_list": [ "../commondata/suite_bibliography.rst" ],
    "rst_epilog_source_list": [ "../commondata/rstepilog_include.py" ],
    "cur_proj_intersphinx_map_name": "sqsh"
            }

“cur_proj_intersphinx_map_name” : “mysite”

在项目级别上，Sphinx Refmate 可以定义一个额外的设置，这在默认/用户设置中是不可用的。这就是 cur_project_intersphinx_map_name。这为 Sphinx Refmate 提供了一种确保的方式来识别 intersphinx_mapping 变量中的当前项目行。请注意，不需要实现此设置，因为 Sphinx Refmate 有相当可靠的方式来确定哪个 intersphinx_mapping 行与当前项目相关。然而，您确实应该设置此变量，以克服 Sphinx Refmate 可能报告的有关无法识别当前项目的任何错误。

快捷键绑定

默认情况下没有启用快捷键绑定。可以通过 偏好设置 -> 包设置 -> Sphinx Refmate -> 快捷键 来编辑插件快捷键，这会显示示例/用户快捷键的结对面板。可以将示例快捷键复制到活动快捷键文件中，以启用它们，并根据用户偏好进行配置。

快速面板显示键

对于 ref/doc/term 类型引用的列表，快速面板中的行将以被引用项目的 intersphinx_mapping 名称作为前缀，例如 myproj>。此外，可能有一个星号前缀，例如 *myproj>，表示该引用属于当前项目（当前正在编辑的项目）。

对于引用/替换类型引用的列表，将没有前缀。这些类型的引用始终来自正在编辑的当前项目。

intersphinx_mapping 变量

SphinxRefmate 使用 intersphinx_mapping 变量和它们指向的 objects.inv 文件，以便文档编写者更好地管理引用。管理三个 Sphinx Doc 项目交叉引用的 intersphinx_mapping 变量可能看起来像这样

intersphinx_mapping = {
    'rug': ('https://rugby.org', ('_build/html/objects.inv', '../commondata/rug_objects.inv')),
    'sqsh': ('https://squash.org', ('_build/html/objects.inv', '../commondata/sqsh_objects.inv')),
    'can': ('https://canasta.org', ('_build/html/objects.inv', '../commondata/canny_objects.inv'))
    }

提供多个目标给清单的能力，如上所示，是在 Sphinx Docs v1.3 中出现的。这就是 Sphinx Refmate 使用并期望定义的 intersphinx_mapping 类型。Sphinx Refmate 只查找 objects.inv 文件的文件路径位置。Sphinx Intersphinx 扩展允许 objects.inv 文件位于网站位置，但 Sphinx Refmate 跳过了 intersphinx_mapping 变量中的此类设置（这样做的设计选择是为了参考速度）。有关 Intersphinx 和 intersphinx_mapping 变量的更多信息，请参阅 Sphinx Intersphinx 扩展文档。

注意：如果您只处理一个 Sphinx Docs 项目，并且不希望交叉引用其他项目，则没有必要运行 Intersphinx 扩展。在这样一个项目上有意义地使用 Sphinx Refmate 仍需要定义 intersphinx_mapping 变量。

支持 intersphinx_mapping 变量的单项目 Sphinx Refmate 可能会在 conf.py 中定义，如下所示

intersphinx_mapping = {'cpract': ('https://choir.practice.org',
                                  ('_build/html/objects.inv', '../commondata/cpo_objects.inv'))}

objects.inv 文件管理

Sphinx Doc 建筑过程将在构建根目录中输出项目的一个 objects.inv 文件。对于 html 构建，这通常意味着 _build/html 目录。在上述 intersphinx_mapping 示例中，每次给清单文件提供的第一个位置如下所示。然而，构建目录通常会被清空，甚至可能为空，当您在使用 Sublime Text 编辑源文件时。在这种情况下，如果尝试激活 Sphinx Refmate 依赖于 objects.inv 的功能，它将会失败。

确保 Sphinx Refmate 交叉引用始终完全可用的一种有效方法，是定期将项目的 objects.inv 文件从标准位置复制到一个更安全的位置。可以设置 systemd 定时器或 cron 任务来执行此操作。在这些更安全的位置（如上述示例中的 ../commondata），objects.inv 文件将更持久可用。

关于跨项目 Sphinx 文档引用和 intersphinx_mapping 变量的某些问题

注意： 项目 intersphinx_mapping 的简短名称是为了识别用户在其映射设置时选择的项目的简写。

识别当前项目

Sphinx Refmate 需要能够识别其正在运行的本地 Sphinx 文档项目并将其与 intersphinx_mapping 中的条目关联。这是必需的，因为通常 Sphinx Refmate 只被用来为当前项目提供引用。

识别哪些 Sphinx 文档项目是私有的（例如，基于 LAN）或公共的（例如，基于互联网）

Sphinx Refmate 需要知道 Sphinx 文档项目是私有的还是公共的，因为将无法访问的链接插入到公共网站上是没有意义的（对于 HTML 网站构建）。

修改现有的 Sphinx 文档项目来利用 Sphinx Refmate

考虑到以上内容，如果其开发人员想开始使用 Sphinx Refmate，现有 Sphinx 文档项目可能需要进行一些微小修改。可能需要发生的修改类型包括

• 更改或实现 intersphinx_mapping 变量，并确保它包含到 objects.inv 文件的稳健路径。
• 更改 intersphinx_mapping 中项目的 '短名称'，使其符合私用/公共的概念。如果是这种情况，那么更改所有连接到的 reST 源文件中的引用也将是必要的。