在 Sphinx 和 reStructuredText 中引用带有数字的数字答案

【问题标题】：Referencing figures with numbers in Sphinx and reStructuredText在 Sphinx 和 reStructuredText 中引用带有数字的数字
【发布时间】：2011-02-10 19:03:09
【问题描述】：

在编写将使用Sphinx 处理的 RST 时，我无法让 Sphinx LaTeX 输出在引用数字时使用数字数字。比如这段代码：

The lemmings are attacking, as can be seen in :ref:`figlem`.

.. _figlem:

.. figure:: _static/lemming_invasion.* 

   They're coming!

会转换成这个：

旅鼠正在攻击，可能是 他们来了！

/图片放在这里/

图 1.1：他们来了！

但我想要的是引用数字的“标准”LaTeX 方式，如下所示：

旅鼠正在攻击，可能是如图1.1所示

我如何实现这一目标？我目前使用的代码是 Sphinx 手册推荐的，但它不会产生我想要的输出。

【问题讨论】：

看起来需要一个重要的功能。
您找到解决方案了吗？我真的很需要这个功能。
@jterrace 不，从未找到解决方案。
@Lucas 在我的回答中找到了一个模块
@jterrace 遗憾的是，当我试图解决这个问题时，该模块并不存在。不过，感谢您找到它并发布答案；希望它可以帮助处于相同情况的其他人。

标签： restructuredtext python-sphinx

【解决方案1】：

在最新版本的 Sphinx (1.3+) 中，数字编号和从文本中引用它们变得更加容易，因为现在内置了对它的支持。

在您的文本中，您可以执行以下操作：

.. _label:
.. figure:: images/figure.*


At :numref:`label` you can see...

最终结果应该类似于“在图 1.1 中您可以看到...”。此技术适用于默认 HTML 输出和 LaTeX 输出。

在您的conf.py 文件中，确保设置标志numfig = True。还有参考文本格式的配置选项（numfig_format 和 numfig_secnum_depth）。

参考资料：

【讨论】：

最近的链接：sphinx-doc.org/en/master/usage/restructuredtext/…
谢谢，@wkschwartz - 我更新了帖子上的链接。

【解决方案2】：

numfig 扩展正是这样做的。我试过了，它对我有用。

【讨论】：

这最初对我不起作用（对于 HTML），但我在这里使用了 'rrieber' 的修复：bitbucket.org/arjones6/sphinx-numfig/issue/6/… 并且能够让它工作。谢谢！
你是如何让它工作的？ rrieber 提供的差异文件与我从该 bitbucket 存储库中获取的 numfig.py 不匹配。
试试我在这里更新的版本：github.com/jterrace/sphinxtr/blob/master/extensions/numfig.py（删除对 figtable 和 subfig 模块的引用）
如果能提供一个语法示例以供快速参考就好了。
现在已内置在 sphinx 中。

【解决方案3】：

要扩展已接受的答案，您可以按如下方式快速进行此设置。将numfig.py 文件放在您的source 目录中。然后打开conf.py 并取消注释该行

sys.path.insert(0, os.path.abspath('.'))

然后将'numfig' 添加到extensions 列表中。

要在您的rst 文档中使用，请首先标记您的图形（例如，fig-main）：

.. _fig-main:

.. figure:: main.png

   This is the figure caption.

最后，您可以使用:num: 指令引用它的图号，如下所示：

Refer to the main figure (Figure :num:`fig-main`).

【讨论】：

这个现在是内置的，内联角色被称为：numref sphinx-doc.org/en/stable/markup/…

【解决方案4】：

我认为引用 Figures 尚未在 reST 中实现，但这里有一个解决方法 http://article.gmane.org/gmane.text.docutils.user/5623 可以让您更接近。

【讨论】：

遗憾的是，这似乎不适用于 Sphinx。不过感谢您的尝试。

【解决方案5】：

可以使用原始乳胶代码，内联。对于上面的示例，首先定义原始乳胶代码的角色，然后使用\ref{}latex 命令引用图形，并使用\label{}latex 命令为图形设置标签。

以下应该有效：

.. role:: raw-latex(raw)
     :format: latex

The lemmings are attacking, as can be seen in :ref:`figlem`
on figure :raw-latex:`\ref{pic:lem}`.

.. _figlem:

.. figure:: _static/lemming_invasion.* 

   They're coming! :raw-latex:`\label{pic:lem}`

请注意，\label{} 命令将出现在 tex 文件的标题中，但它仍然可以接受，至少在pdflatex 方面是可以接受的。另请注意，:raw-latex 之前至少应有一个空格。

【讨论】：