我正在使用docutils自带的rst2html
工具将reST转换为HTML。似乎代码已经将id
属性分配给了各个部分,这可以用作URL的片段标识符,即锚点,以跳转到页面的特定部分。这些id
值基于节标题的文本。当我更改该标题的措辞时,标识符也会更改,从而使旧URL无效。
是否有一种方式指定要用作给定部分标识符的名称,以便我可以编辑标题而不使链接失效?如果我从自己的脚本中调用docutils publisher,是否有一种方法可行呢?
我正在使用docutils自带的rst2html
工具将reST转换为HTML。似乎代码已经将id
属性分配给了各个部分,这可以用作URL的片段标识符,即锚点,以跳转到页面的特定部分。这些id
值基于节标题的文本。当我更改该标题的措辞时,标识符也会更改,从而使旧URL无效。
是否有一种方式指定要用作给定部分标识符的名称,以便我可以编辑标题而不使链接失效?如果我从自己的脚本中调用docutils publisher,是否有一种方法可行呢?
我认为在reST部分中无法设置显式id,但我可能错了。
如果您更喜欢编号的id,这将取决于文档树中部分的排序而不是它们的标题,您可以通过对docutils / nodes.py中document.set_id()方法进行小修改来实现。
这里是补丁:
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命令中进行补丁操作。
我不确定是否真正理解了你的问题。
您可以创建明确的超链接目标,以引用文档中的任意位置,这些位置与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和主题。您不仅可以使用Sphinx编写源代码文档,还可以进行一般文本处理。像Sphinx文档本身就是一个例子(在readthedocs上有数百个其他例子)。
使用sphinx-quickstart
调用Sphinx很简单。您只需将现有的rst文件添加到index.rst
的toctree中,然后运行make html
。如果您想记录Python代码,可以使用sphinx-apidoc
自动生成API文档。
html
和singlehtml
构建看起来非常有前途,尽管我仍然需要重写我的文档才能使其正常工作,因此我还不能确定结果是否令人满意。我仍然想了解如何调整基本的rst2html
以使用自定义锚点。这意味着我可能最终会像你建议的那样使用Sphinx,并将赏金授予Tobia,因为他的答案更接近我的问题。希望你不要太介意。 - MvGindex.rst
中。由自动生成的 TOC 使用的各个部分的锚点再次来自于部分标题,而不是来自于这些标题之前的显式链接目标。只有整个文档具有从文件名形成的锚点。因此,为了使其有用,我将不得不将我的文档拆分为每个函数一个文件。然后它可能会起作用,尽管我想找到一些方法在 singlehtml
构建中省略这个 document-
前缀。 - MvG.. _a-section:
First Chapter
-------------
“第一章”的永久链接将指向#a-section
而不是#first-chapter
。如果有多个,则选择最后一个。