python-sphinx - 使用 :numref: 通过图编号引用 reStructuredText 中的图

Question

我目前正在尝试设置 reStructuredText 模板。我想包括编号的数字和对这些数字的引用。因此，我按照 sphinx 文档 ( http://www.sphinx-doc.org/en/stable/markup/inline.html ) 中给出的说明进行操作。

首先我添加了该行

numfig = True

在文件“conf.py”中。我在文件“rstTemplate.rst”中实现了该图及其引用，如下所示:

.. _my-figure:

.. figure:: images/scen-smartcity.*
    :scale: 50 %
    :alt: smartcity symbol
    :align: center

    This is the caption of the figure (a simple paragraph).

    This is the legend of the figure

Reference to the figure :numref:`(Fig. %s) my-figure`

当我使用 make html 构建 html 文件时

Running Sphinx v1.6.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 2 changed, 0 removed
reading sources... [100%] rstTemplate
rstTemplate.rst:: WARNING: duplicate label my-figure, other instance in ><path-to-file>\rstTemplate.rst
<path-to-file>\rstTemplate.rst:: WARNING: duplicate label my-figure, other instance in <path-to-file>\index.rst
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] rstTemplate
rstTemplate.rst:41: WARNING: undefined label: (fig. %s) my-figure
<path-to-file>\rstTemplate.rst:41: WARNING: undefined label: (fig. %s) my-figure
generating indices... genindex
writing additional pages... search
copying images... [100%] images/scen-smartcity.svg
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 6 warnings.

文件index.html然后显示图形、标题和对其的引用，如下所示: output index.html

所以标题显示了一个很好的“图”。 1' 但使用 :numref: 的引用显然不起作用。我也尝试过

:numref:`my-figure`

这导致了类似的结果。

有人知道为什么这里的引用不起作用吗？

同样有趣的是:上面提到的所有内容都在我的文件“rstTemplate.rst”中，我通过 .. include::rstTemplate.rst 将其包含在文件“index.rst”中。 html 构建后，我收到文件“index.html”和“rstTemplate.html”。与“index.html”版本不同，“Fig. 1' 未包含在“rstTemplate.html”中的图标题中。这可能与这里出现的问题有关吗？

提前致谢。

Answer 1

假设您的 conf.py 包含以下内容:

import sys
import os
html_theme = 'sphinx_rtd_theme'
numfig = True

并且您的index.rst包含:

.. toctree::
   :maxdepth: 2
   :caption: Home
   :hidden:

 mychapter

这是章节 RST 文档 mychapter.rst 的工作示例:

.. figure:: images/my-image.png
   :name: my-custom-label

This is a caption of the image

This is a reference to :numref:`my-custom-label` bla bla ...

这呈现为:

This is a reference to Fig.1 bla bla ...