13

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

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

4

2 回答 2

4

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

如果您希望有编号的 id，这将取决于文档树中各部分的顺序，而不是它们的标题，您可以通过对 docutils/nodes.py 中的 document.set_id() 方法稍作更改来实现（在我的版本的第 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 命令对其进行猴子修补。

于 2013-03-14T14:02:06.657 回答
3

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

您可以创建指向文档中任意位置的显式超链接目标，这些位置可用于引用这些位置，而与 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它，因为它可以处理对不同文件之间任意位置的引用，并且具有更多优势，例如toctree和theming。您不仅可以将 sphinx 用于源代码文档，还可以用于一般文本处理。Sphinx 文档本身就是一个例子（在readthedocs上有数百个其他例子）。

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

于 2013-03-17T11:08:25.210 回答