标签: python-sphinx

我在 Sphinx 中创建教材，我经常想将学生重定向到给定的手册页。Sphinx 有一个很好的内部语法，例如:manpage:ls(1). 不幸的是，Sphinx 只对此应用了一些格式，导致纯文本输出。我希望 Sphinx 使用给定的联机帮助页呈现指向某个网页的链接，就像它的做法一样:rfc:标记的方式。

以某种方式可行吗？有没有办法轻松重写:manpage:宏，这样我就可以做到这一点？

如何将外部文件包含为类似于代码块的 Sphinx 文档？

我怎样才能让它设置语法颜色的样式？

这是我第一次在 PyCharm 5.0 和 Python 3.5 中使用 Sphinx。

当我sphinx task在 PyCharm 中运行时，出现以下错误：

File "C:\Program Files (x86)\JetBrains\PyCharm 5.0\helpers\docutils\__init__.py", line 63, in <module>
    class ApplicationError(StandardError): pass
NameError: name 'StandardError' is not defined

在这个页面上，我发现在 Python 3.xStandardError中现在被替换为Exception. 但是，当我尝试编辑__init__.py文件时，PyCharm 阻止我保存它。

我还注意到它__init__.py基于 docutils 0.8 版。这并不直观，因为我在我的 virtualenv 中安装了 docutils 0.12 版。这意味着版本 0.12 被忽略。

有谁知道如何解决这一问题？

任何想法为什么 sphinx 不创建交叉引用链接？

我已经尝试了所有可能的组合来尝试获得工作链接，但没有运气。我试过napoleon_google_docstring打开和关闭。

其他自动创建的引用工作正常。

正如标题所述，我正在使用 sphinx-doc，当构建输出为 latexpdf 时，我真的想有条件地呈现静态 PNG，而为 Web 构建时，我真的想有条件地呈现动画 GIF。

理想情况下，能够以某种方式在 rst 文件本身中执行此操作会很好......语义上是：

if builder == html: .. image: blah blah elif builder == latexpdf: .. image: blah blah

我正在用Sphinx创建一个文档，我在其中引用标准数字引用方式的论文，例如

文件1.rst

骨骼、细胞外基质[2]、体液和扩散化学物质[3]

参考文献.rst

.. [2] 默克斯，RMH，纽曼 <MoreText>

.. [3] 图灵，上午 <MoreText>

但它不起作用。我看到的数字引用仅脚注和你在提到使用字母文本引用文档。

我相信很多人都使用编号的参考文献进行引用。有没有办法做到这一点？

Sphinx与ReadTheDocs主题一起使用时是否可以隐藏侧边栏？

进一步扩展问题，我可以在发出命令时包含侧边栏：

$ 制作 html

并且不包括它发出命令：

$ make htmlhelp

不改变代码？也许在 layout.html 中添加一些东西。

我有一个脚本可以生成一些数字并将它们放在报告的附录中，例如

Appendix
********

.. figure:: images/generated/image_1.png
.. figure:: images/generated/image_2.png
.. figure:: images/generated/image_3.png
... etc

看起来在大量（约 50 个）图像之后，我的pdflatex命令将挂起，并指向.tex此处文件中的一个图形

...
\begin(figure)[htbp]
\centering
\noindent\sphinxincludegraphics{{image_49}.png}
\end{figure}

\begin(figure)[htbp]
\centering
\noindent\sphinxincludegraphics{{image_50}.png} <--- here
\end{figure}

\begin(figure)[htbp]
\centering
\noindent\sphinxincludegraphics{{image_51}.png}
\end{figure}
...

当pdflatex失败时，我真的无法从控制台输出中弄清楚要做什么，我得到了一些似乎是好消息的行

<image_48.png, id=451, 411.939pt x 327.3831pt>
File: image_48.png Graphic file (type png)
<use image_48.png>
Package pdftex.def Info: image_48.png  used on input line 1251.
(pdftex.def)             Requested size: 411.93797pt x 327.3823pt.

<image_49.png, id=452, 411.939pt x 327.3831pt>
File: image_49.png Graphic file (type png)     
<use …

如果我定义 aglossary和一个称为 的术语foobar，则可以将文本中的该术语用作

This is a ref to the :term:`foobar` term.

这将foobar成为一个可点击的参考，将我带到词汇表。

但是，如果我想引用一个术语但以不同的方式显示它，例如，复数形式，例如“我有很多 foobars”，其中 foobar 被识别为术语并链接到词汇表，该怎么办？

以下内容不会作为紧跟在关闭反勾号之后的字符工作，将把它弄乱，因此它根本不会被识别为术语链接。

I have many :term:`foobar`s

在 s 之前添加一个空格显然看起来很糟糕。如果可以将整个单词“foobars”标记为指向该术语的链接，那就太好了foobar。这可能吗？

我发现.. include::指令对于文本重用非常有用：相同的部分可以插入到不同的文档中。

但是标题级别存在问题。

例如，如果我有part.rst二级标题

part.rst

Header level 2
----------------

My text to be included

并将其包含在具有各种标题级别的不同文档中

doc 1

Header level 1
================

.. include::  part.rst

doc2

Header level 2
----------------

.. include::  part.rst

doc 3

Header level 3
~~~~~~~~~~~~~~~~~

.. include::  part.rst

永远都是2级。控制不了。

我读过关于sphinx.ext.ifconfig – Include content based on configuration，我可以用

part.rst

.. ifconfig:: hide_part_rst_title

    Header level 2
    ----------------

My text to be included

但是看起来在许多零件文件的情况下创建了许多变量。

可能有更优雅的方式吗？

如何包含.rst没有原始标题的文件？如果我裁剪这个，我可以像这样在每个地方添加一个标题

.. doc 1
Header level 1
================ …