在 reST 中指定锚名称

Question

我正在使用 docutils 附带的 rst2html 工具从 reST 创建 HTML。似乎代码已经为各个部分分配了id 属性，这些属性可以用作 URL 中的片段标识符，即作为跳转到页面特定部分的锚点。这些id 值基于部分标题的文本。当我更改该标题的措辞时，标识符也会更改，从而使旧 URL 无效。

有没有办法指定名称作为给定部分的标识符，这样我就可以在不使链接失效的情况下编辑标题？如果我自己从自己的脚本中调用 docutils 发布者，会有办法吗？

Answer 1

我认为您不能在 reST 部分中设置显式 id，但我可能弄错了。

如果您希望有编号的 id，这将取决于文档树中各个部分的顺序，而不是它们的标题，您可以通过对 docutils/nodes 中的 document.set_id() 方法稍作更改来做到这一点.py（在我的版本的第 997 行。）

这是补丁：

 def set_id(self, node, msgnode=None):
     for id in node['ids']:
         if id in self.ids and self.ids[id] is not node:
             msg = self.reporter.severe('Duplicate ID: "%s".' % id)
             if msgnode != None:
                 msgnode += msg
     if not node['ids']:
-        for name in node['names']:
-            id = self.settings.id_prefix + make_id(name)
-            if id and id not in self.ids:
-                break
-        else:
+        if True: #forcing numeric ids
             id = ''
             while not id or id in self.ids:
                 id = (self.settings.id_prefix +
                       self.settings.auto_id_prefix + str(self.id_start))
                 self.id_start += 1
         node['ids'].append(id)
     self.ids[id] = node
     return id

我刚刚对其进行了测试，它生成的部分 id 为 id1、id2...

如果您不想更改此系统范围的文件，您可以使用自定义 rst2html 命令对其进行猴子修补。

Answer 2

我不确定我是否真的理解你的问题。

您可以在文档中的任意位置创建explicit hyperlink targets，这些位置可用于引用这些位置，而与 docutils 创建的隐式超链接目标无关：

.. _my_rstfile:

------------------
This is my rstfile
------------------

.. _a-section:

First Chapter
-------------

This a link to a-section_ which is located in my_rstfile_.

您似乎想在多个 rst 文件之间创建链接，但我建议使用 Sphinx，因为它可以处理不同文件之间对 arbitrary locations 的引用，并且具有更多优势，例如 toctree 和 @ 987654325@。您不仅可以将 sphinx 用于源代码文档，还可以用于一般文本处理。 Sphinx documentation 本身就是一个例子（readthedocs 上还有数百个其他例子）。

使用sphinx-quickstart 调用Sphinx 应该很简单。您可以简单地将现有的 rst 文件添加到 index.rst 中的目录树并运行 make html。如果你想记录 python 代码，你可以使用sphinx-apidoc，它会自动生成一个 API 文档。