如何在 reStructuredText / Sphinx 中创建浮动图形？

Question

我想要一个带有文字的图形。

这就是我要说的：

Installation of Optional Accessories
====================================

.. warning:: Never plug in or unplug a Hand Robot or a Grasp Sensor while the robot is turned on, as the system will not function properly and damage to the robot could occur.

Installing a Hand Robot
-----------------------

.. _`fig-attach-hand-robot`:
.. figure:: attach-hand-robot.*
  :scale: 40%
  :align: right

  Attach Hand Robot

Make sure the robot is turned off as described in the section :ref:`turn-off-robot`. 

Take the hand robot out of the grounded bin that sits on top of the electrical panel (if you have an adjustable height table) or sits on top of the rear table (if you have a fixed height table). Make sure not to touch the pins on the electrical wiring while doing so. Insert the conical protrusion of the hand robot into the conical receptacle (see :ref:`fig-attach-hand-robot`). Once the hand robot is supported by the InMotion Arm Robot, make sure the two knobs below the Hand Robot have engaged and sprung in. If they have not, twist them until they do as shown (see :ref:`fig-knobs-in`).

和this screenshot of PDF output is what I'm getting.

• 为什么图形标题居中，而不是在图片下方？
• 为什么正文（“确保...”和“采取...”）不在图像的左侧，而不是在其下方？我希望图形向右浮动，并在其左侧显示文本。

Answer 1

我发现数字浮动到指定了:figwidth: 和:align: 的一侧。 （使用 readthedocs 主题。）

..  figure:: images/myimage.jpg
    :figwidth: 40%
    :align: right

https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure

Answer 2

所以，我对 reStructuredText 做了一些研究，看来你想要的实际上是不可能的。

figure 和 image 指令的文档从未提及在对象周围环绕文本的能力。

这可能是提供给 Sphinx 开发人员的功能请求，尽管我怀疑他们会拒绝它，因为它没有在第一个规范中明确提及。

我希望赏金会引起一些关注，但我怀疑没有。

Answer 3

虽然为时已晚，但也许答案会对未来的人有所帮助。

您可以使用侧边栏指令来放置图像。

.. sidebar:: mandatory_title. Use can use image caption here

     .. Figure:: 1.png

Answer 4

为了处理图像，因为它们是文本的一部分，您实际上可以使用substitutions。

此处摘录的文档可能会有所帮助：

The |biohazard| symbol must be used on containers used to
dispose of medical waste.

.. |biohazard| image:: biohazard.png

希望对你有帮助

Answer 5

如果其他人遇到这个问题，那么这段代码可能会有所帮助。我决定我不想破解实际的 sphinx 代码，所以我制作了一个非常短的 python 脚本，应用于生成的_build/latex/pi3d_book.tex，以将之前或之后具有\hfill 的\includegraphics 转换为包装图像。会有很多事情阻止这种工作，例如将图像放入列表或缩放图像。我的第一个狮身人面像指令就像

.. image:: perspective.png
   :align: right

您显然必须更改文件名和路径以适合您的设置。从我的 spinx 项目中我运行

$ make latexpdf
$ python wrapfix.py # or whatever you call this file

wrapfix.py的节目列表

import subprocess

with open("_build/latex/pi3d_book.tex", "r") as f:
  tx = f.read().splitlines()

txnew = []
flg1 = True
for line in tx:
  if line == "" and flg1:
    txnew += ["\\usepackage{wrapfig}",""]
    flg1 = False # just do this once before first blank line
  elif "includegraphics{" in line and "hfill" in line:
    fname = line.split("{")[2].split("}")[0]
    if line.startswith("{\\hfill"): # i.e. right justify
      fl_type = "R"
    else:
      fl_type = "L"
    txnew += ["\\begin{wrapfigure}{" + fl_type + "}{0.35\\textwidth}",
              "\\includegraphics[width = 0.3\\textwidth]{" + fname + "}",
              "\\end{wrapfigure}"]
  else:
    txnew += [line]

txnew = "\n".join(txnew)
with open("_build/latex/pi3d_book.tex", "w") as fo:
  fo.write(txnew)

subprocess.Popen(["pdflatex", "pi3d_book"], cwd="/home/jill/pi3d_book/_build/latex")