在reST中指定锚点名称

Question

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

有没有一种方法可以指定名称作为给定部分的标识符，这样我就可以编辑标题而不会使链接失效？如果我自己打电话给docutils出版商，从我自己的剧本里，有没有办法？在

Answer 1

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

如果您希望对id进行编号，这将取决于文档树中各节的顺序，而不是它们的标题，那么只需对document.set_id文件（）docutils中的方法/节点.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

我刚刚测试了它，它生成了id1，id2的部分ID。。。在

如果您不想更改这个系统范围的文件，您可以通过一个自定义的rst2html命令对其进行monkey补丁。在

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文件之间创建链接，因此我建议使用^{}，因为它可以处理不同文件之间对arbitrary locations的引用，并且有一些其他的优点，比如toctree和{a5}。您不仅可以将sphinx用于源代码文档，还可以用于一般文本处理。与示例类似的是Sphinx documentation本身（在readthedocs上还有数百个其他示例）。在

使用^{}调用Sphinx应该很简单。您只需将现有的rst文件添加到index.rst中的目录树中，然后运行make html。如果您想记录python代码，可以使用^{}，它将自动生成API文档。在