标签: python-sphinx

跑步时

sphinx-build . html/

在我的doc/目录中，我得到以下输出：

$ sphinx-build . html/
Running Sphinx v0.6.4
No builder selected, using default: html
loading pickled environment... done
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] index                 
reST markup error:
HIDDEN/PATH/matplotlib_visualization.py:docstring of simulator.extensions.matplotlib_visualization.beta:20: (SEVERE/4) Unexpected section title.

这个文件有numpy导入，经过一些研究，似乎 sphinx 使用的 RST 标记在记录方式上有问题numpy。当我取出 numpy 导入时，html 构建良好。

解决此问题的最佳方法是什么？

我正在开发一个非常庞大的代码库,它使用sphinx-apidoc从Python源代码中的docstrings自动生成HTML文档.文档字符串使用以下格式:

:param message:要显示的消息
:type message:string
:returns:formatted string
:rtype:string

要求将Sphinx HTML文档替换为以不同方式组织/呈现的内容 - 但我们仍然希望从源文档中自动生成文档字符串.有没有办法用Sphinx以中介(如xml)格式生成文档？我发现没办法做到这一点.谁知道我会做什么？

我在 Sphinx reST 中有一个文档集。我在 conf.py 中包含了 sphinx.ext.mathjax，并包含了“mathjax_path = ' http://cdn.mathjax.org/mathjax/latest/MathJax.js '”这一行。我相信这就是在向 rst 文件添加标记之前我需要做的所有事情。但是我的方程没有被渲染。例如，

:math:`a^2 + b^2 = c^2`

从浏览器中出来

\(a^2 + b^2 = c^2\)

没有花哨的字体或任何东西。HTML是

<span class="math">\(a^2 + b^2 = c^2\)</span>

我使用的 Sphinx 模板（例如sphninxdoc或sphinx13）有一个指向“contents.rst”文件的链接；但是，尽管此文件被记录为 "special"，但我看不到生成它的方法。

有没有办法让 Sphinx自动生成“contents.rst”，还是我需要手动生成它？

使用重组文本，我已经看到了这两种用法：

`Some Link <http://www.some.com>`_
`Some Link <http://www.some.com>`__

两者都从Sphinx生成相同的输出，

对URL链接使用_或使用双下划线有什么区别？__http

你为什么要一个接一个？

我不确定这是否可能。但我希望将多个 .rst 文件放在一个目录中，并在编译期间。我希望这些文件自动插入到toctree. 我该怎么办？

在Sphinx中,可以使用以下语法生成文件链接:

`name_of_file.js <some/location/name_of_file.js>`_

在conf.py文件中,version定义了一个变量,我们可以在.rst文件中使用这样的变量:

|version|

不允许使用该语法将版本包含到文件链接中:

`name_of_file.|version|.min.js <some/location/name_of_file.|version|.min.js>`_

那么,我如何生成指向类似文件的链接name_of_file.<version_num>.min.js并使用conf.py中的版本号？

有没有办法在重组文本中将长列表分成多列？

来源：

* a
* b
* c
* d
* e
* a
* c
* a
* d
* e
* f

结果：

* a   * e   * d
* b   * a   * e
* c   * c   * f
* d   * a

目标是在 reST 指令中提供源列表，而不是使用某种其他语言来读取源列表，然后在 reST 中使用“.. raw::”指令写入结果文本。例如这个假设list-multicol指令：

.. list-multicol::
   :columns: 3

   * a
   * b
   * c
   * d
   * e
   * a
   * c
   * a
   * d
   * e
   * …

我正在为 Sphinx/rst 编写一些文档。如何链接到本地​​磁盘上与您正在查看的页面相关的内容？

例如：

====================
My App documentation
====================

The official My App documentation can be found here:
https://myapp.com/docs

A local mirror is available:
../../_static/docs_mirror/index.html

在我的机器上，_static 文件夹位于：

file:///Users/fredrik/code/repos/myapp/docs/_static

...但我不想对该路径进行硬编码，因为对于已下载克隆存储库的另一个用户而言，该路径可能与该路径不同。

我要记录的项目结构如下：

/top
Index.rst
     /a
     toctree_a.rst (contains doc and doc2)
     doc.rst
     doc2.rst
     /b
     toctree_b.rst (contains doc4 and doc3)
     doc3.rst
     doc4.rst

我想引用toctree子目录（a和b）中的s，以便项目toctree可以看到项目树中的4个文档。

当文档位于一个目录中时，我知道如何执行此操作，但如果将它们放在子目录中，我不知道如何执行此操作。我试图保持我的项目结构完整，而不必将所有文件移动到一个目录中。我做了一些研究，发现这 .. include:: directive可能是要走的路线，但我不知道如何正确使用它。