Question

我正在使用doctils附带的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 ......

的部分ID

如果您不想更改此系统范围的文件，您可以使用自定义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_.

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

使用readthedocs调用Sphinx应该很简单。您只需将现有的rst文件添加到index.rst中的toctree并运行make html即可。如果你想记录python代码，你可以使用sphinx-quickstart自动生成API文档。

在reST中指定锚名称

2 个答案: