使用 :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

所以标题显示了一个很好的 'Fig. 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

您应该使用以下语法

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

如 http://www.sphinx-doc.org/en/stable/markup/inline.html?highlight=numfig#role-numref

所述

独立评论：您可以使用 figure 指令的 :name: my-figure 选项代替 .. _my-figure: 标签。

关于：

I also tried
:numref:`my-figure`
which led to a similar result.

我无法重现。它对我有用。更广泛的语法

:numref:`(Fig. %s) <my-figure>`

以上只需要自定义格式即可，这里指的是加括号。

Answer 2

假设您的 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 ...

使用 :numref 通过图形编号在 reStructuredText 中引用图形：

Reference Figures in reStructuredText via Figure Numbers using :numref:

restructuredtext

python-sphinx