将交叉引用添加到另一个页面中的子标题或锚点

Question

如何将reST/Sphinx页面中的交叉引用插入同一文档集中另一页的子标题或锚点？

Answer 1

表达"reST/Sphinx"使问题的范围不清楚.它是关于reStructuredText 和 Sphinx,还是只关于Sphinx中使用的 reStructuredText (而不是一般的reStructuredText)？我将介绍两者,因为使用RST的人可能在某些时候遇到这两种情况:

狮身人面像

除了可用于链接到各种实体(如classes(:class:))的特定于域的指令之外,还有一般:ref:指令,在此处记录.他们给出了这个例子:

    .. _my-reference-label:

    Section to cross-reference
    --------------------------

    This is the text of the section.

    It refers to the section itself, see :ref:`my-reference-label`.

虽然RST提供的一般超链接机制在Sphinx中有效,但文档建议在使用Sphinx时不要使用它:

建议使用ref通过标准的reStructuredText链接到部分(如Section title_),因为它可以跨文件,更改节标题时以及支持交叉引用的所有构建器.

RST,总的来说

将RST文件转换为HTML的工具不一定具有集合概念.例如,如果您依赖github将RST文件转换为HTML或者使用命令行工具,就是这种情况rst2html.不幸的是,用于获得所需结果的各种方法取决于您使用的工具.例如,如果您使用rst2html并希望文件A.rst链接到文件中名为"Section"的部分,other.rst并且您希望最终的HTML在浏览器中工作,那么A.rst将包含:

`This <other.html#section>`__ is a reference to a section in another
file, which works with ``rst2html``. Unfortunately, it does not work
when the HTML is generated through github.

您必须链接到最终的HTML文件,您必须知道id该部分的给定内容.如果你想对通过github提供的文件做同样的事情:

`This <other.rst#section>`__ is a reference to a section in another
file, which works on github. Unfortunately, it does not work when you
use ``rst2html``.

在这里你也需要知道id该部分的给定.但是,您链接到RST文件,因为它只在访问创建HTML的RST文件时.(在撰写本答案时,不允许直接访问HTML.)

这里有一个完整的例子.

Answer 2

2016年新的,更好的答案!

自动切片扩展可让您轻松完成此操作.

=============
Some Document
=============


Internal Headline
=================

然后,以后......

===============
Some Other Doc
===============


A link-  :ref:`Internal Headline`

此扩展程序是内置的,因此您只需编辑即可 conf.py

extensions = [
    .
    . other
    . extensions
    . already
    . listed
    .
    'sphinx.ext.autosectionlabel',
]

您唯一需要注意的是,现在您无法在整个文档集合中复制内部标题.(值得.)

Answer 3

忽略这个答案,它不起作用:更好地使用答案 __CODE__

对于锚点,您可以定义"短"锚点名称,如下所示:

.. _ShortAnchor:

Target Header goes here
=======================

Some text.

要引用该标题,请使用:

For more details, see ShortAnchor_.

请注意,这甚至会将ShortAnchor扩展为标题的全名.

您也可以使用完整的标题名称,如:

See `Target Header goes here`_ chapter.

但是这更容易修改标题文本.

所有这些都适用于多个源文件,这些文件是最终文档的一部分.

Answer 4

例子：

Hey, read the :ref:`Installation:Homebrew` section.

在哪里Homebrew是名为Installation.rst.

这使用autosection 功能，因此需要config.py使用以下内容进行编辑：

extensions = [
    'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True

Answer 5

在Sphinx 3.0.3中，唯一对我有用的解决方案是:any:（参见https://www.sphinx-doc.org/en/1.5/markup/inline.html#cross-referencing-anything）。假设一个文档有这样一个部分：

.. _my-section:

My Section
----------

Lorem ipsum blablabla

然后另一个文档可以有以下片段来创建链接：

See :any:`my-section` for the details