标签: python-sphinx

假设我有一张类似的桌子reStructuredText：

+---------------+---------------------------+
| key           | value                     |
+===============+===========================+
| short_word    | value_1                   |
+---------------+---------------------------+
| really_long_  | value 2                   |
| word_I_want_  |                           |
| to_break      |                           |
+---------------+---------------------------+

有没有办法打破左下角单元格中的单词，即使用行继续转义字符或类似的字符，以便它仍然在输出中显示为单个单词？

特别是，我使用 Sphinx 来记录我的 Python 文档，并且由于尾随下划线字符，它将第一行解释为链接目标，从而生成错误。

如果我需要同时支持 30 多个模块的“常规”散文文档和 API 文档，如何最好地构建 Sphinx 文档（用于阅读文档）？

有许多（<10）常规散文文档页面，例如“入门”、“构建代码”、“常见问题解答”、“支持”等。我知道如何处理这些页面。

另一方面，我的项目包含 30 多个模块，这些模块的 API 文档无法从代码（非 Python）中提取，而必须手动编写。每个模块都有 n 个功能，并且每个模块都必须使用相同的结构进行记录。我想要一个.rst每个模块。

因此，我想要的目录结构如下：

docs\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 building.rst\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 faq.rst\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 ...\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 index.rst\n\xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 modules\n    \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 node.rst\n    \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 ...\n

在阅读文档侧导航（即目录）中，我希望看到它表示为

+ Building (header 1)\n - chapter 1 (header 2)\n - ...\n+ FAQ\n - question 1\n - ...\n+ Modules\n + node (header 1 from `modules/node.rst`)\n   - node.foo()\n   - node.bar()\n + ...\n

可以/应该通过将另一个index.rst放在modules？

我正在Sphinx创建文档（我仍在学习基础知识）。在我的项目中，有一些文件的名称很长，我在文档中多次引用它们，因此，为了让我的生活更轻松，我决定使用如下替换：

.. |MyFile| replace:: a_very_very_long_name_for_a_file_v2.0.txt

然后我只需在我|MyFile|想要引用该文件的任何地方键入即可。这工作得很好，但现在我想使版本部分可变，所以当我发布新版本时我不必更改所有别名（我确信我会忘记一些东西）。幸运的是 Sphinx 设置了变量，version所以我尝试了：

.. |MyFile| replace:: a_very_very_long_name_for_a_file_v |version| .txt

但嵌套替换被忽略。我已经在谷歌上搜索了一个多小时了，我很惊讶以前没有人问过这个问题。我看过一些关于解析文字的内容，但我无法让它工作。基于其他别名创建别名应该是很常见的事情，对吧？我错过了什么吗？对此有更好的方法吗？

我正在使用出色的 Sphinx 工具来创建一些文档，并且需要创建一个自定义 HTML div，以便我可以将其样式与 Sphinx 的其他自动创建的 div 区分开来。

使用container 指令可以做到这一点，但问题是，如果我在子小节下方使用此指令，它会自动将使用容器指令创建的 div 嵌套在子小节内，如下所示：

<div id="automatically-created sphinx subsubsection">
   ...
   <div id="my custom container"></div>
</div>

然而，我想要：

<div id="automatically-created sphinx subsubsection">
   ...
</div>
<div id="my custom container"></div>

有什么办法可以做到这一点吗？任何帮助将不胜感激！

附录：

可能解决该问题的一种巧妙方法是创建一个新的子子部分，以便 Sphinx 自动将其放置在与其他子子部分相同的水平上，然后使用 CSS 隐藏其标题等。然而，这种方法的问题在于新的子子部分自动添加到RTD 主题（我正在使用）的侧边栏，但这不是我想要的。

我正在开发一个基于狮身人面像的协作写作工具。用户访问Web应用程序（用python/Flask开发）在sphinx中写一本书并将其编译为pdf。

我了解到，为了从 python 中编译 sphinx 文档，我应该使用

import sphinx
result = sphinx.build_main(['-c', 'path/to/conf',
                            'path/to/source/', 'path/to/out'])

到目前为止，一切都很好。

现在，我的用户希望应用程序向他们显示语法错误。但输出（result在上面的示例中）只给出了退出代码。

那么，如何从构建过程中获取警告列表？

也许我太雄心勃勃，但由于 sphinx 是一个 python 工具，我期望该工具有一个漂亮的 pythonic 界面。例如，输出sphinx.build_main可能是一个非常丰富的对象，带有警告、行号......

与此相关的是，该方法的参数sphinx.build_main看起来就像命令行界面的包装器。

假设我有两个文件a.rst在b.rst同一个文件夹中，a.rst看起来像这样

.. _foo: http://stackoverflow.com

`foo`_ is a website

似乎不允许使用fooin 。b.rst有没有办法定义超链接并在多个文件中使用它们？

跟进

我extlinks按照史蒂夫·皮尔西的建议使用了该扩展。它的实现和文档字符串可以在 github 上看到。

就我而言，我在 conf.py 中定义了维基百科链接

extlinks = {'wiki': ('https://en.wikipedia.org/wiki/%s', '')}

在.rst文件中，像这样使用它们

:wiki:`Einstein <Albert_Einstein>`

其中爱因斯坦将显示为https://en.wikipedia.org/wiki/Albert_Einstein的链接

当我make html在 linux 终端中输入时，出现以下错误。

Could not import extension sphinx.builders.latex (exception: No module named 'docutils.writers.latex2e')

然后我尝试导入 sphinx.builders.latex 但它说找不到它。有没有解决的办法？自从我尝试安装以来，Sphinx 已是最新的，并且有几行内容显示Requirement already satisfied“帮助！”

我正在使用 sphinx 和 autodoc 扩展从 python 模块中的文档字符串自动生成文档。

我目前使用automodule指令来记录模块的所有公共成员

.. automodule::
    :members:

我的模块还有许多私有属性。我想将其中之一包含在文档中。

有没有一种方法可以告诉automodule记录所有公共成员以及这个私人成员？我尝试过使用该:private-members:选项，但这包括所有私人成员。我还尝试手动指定私有属性，但它没有记录任何公共成员。

.. automodule::
    :members: _PRIVATE_ATTR

我想避免仅仅为了添加这个私人成员而手动列出每一个公共成员。

有没有办法用 autodoc 来做到这一点？

有没有办法在 reStructuredText 中对长节标题进行换行？

我的 Linter 一直抱怨超过最大行长度，这让我发疯。

有问题的章节标题包括:any:参考文献，本质上不能将其改写得更短。

我左右搜索了 RST 教程，但没有找到任何语法。

有问题的 RST 解释器是 Python 3.6 上的 Sphinx v1.8.5。

我有一组 rst 文件，我正在使用 sphinx 在 readthedocs 中构建这些文件。这些文件有多个项目符号列表，但它们没有正确呈现。

文本出现，但没有项目符号或嵌套/缩进。

为了确保它不是我的文件，我从 sphinx_rtd_theme 页面（https://github.com/readthedocs/sphinx_rtd_theme/blob/b07560bf97dad3a4266f6145bd4b662ac708ab00/docs/desmo）直接复制粘贴。

这是 rst 应该呈现的内容（::marker对于 html 文件中的每个列表项）

这就是我使用本地 sphinx / rtd 设置构建相同的 rst 时得到的结果

在我的 conf.py 或其他文件中有什么我需要修复的吗？