问题标签 [python-sphinx]

我注意到Sphinx能够以 JSON 格式生成文档。这些文件是做什么用的？

似乎有大量的 Python 文档工具。我遇到的另一个是 epydoc。似乎 Sphinx 是事实上的标准，因为它用于生成官方 Python 文档。有人可以帮我整理一下 Python 文档工具的当前状态吗？

我一直在使用Sphinx和reStructuredText记录一个软件包。

在我的文档中，有一些长代码片段。我希望能够将它们默认隐藏，并带有一个可以展开它们的小“显示/隐藏”按钮（示例）。

有没有标准的方法来做到这一点？

我正在尝试使这个片段工作：

也就是说，使用 include 指令将文件作为块引用包含在内。一旦进入块引用，指令就会被引用。我想要块引用中的文件内容。

知道怎么做吗？

我讨厌 reST，但喜欢 Sphinx。有没有办法让 Sphinx 读取 Markdown 而不是 reStructuredText？

我的文档字符串引用了我定义的其他 python 类。每次 Sphinx 遇到其中一个类时，我都希望它插入指向该类文档的链接。这在狮身人面像中可能吗？

具体来说，我有一个文档字符串，例如：

我可以写：

但我更希望 Sphinx 找到所有匹配的文本Foo并让它看起来好像我输入了 :class:~foo.Foo

在我正在编写的一些 sphinx 文档中，我包含了来自辅助文件的代码示例，如下所示：

这个特定的文档是一个教程，其中的类是逐步建立的。我想做的是包括整个类或单个方法，并且只强调该部分感兴趣的行。这样可以保留上下文，但有趣的部分一目了然。现在我只使用了文本中的行号，这还可以，但远非理想。

查看 sphinx 和 pygments 的文档和代码，我没有找到明显的方法来做到这一点。我不反对修补它们或做一些棘手的事情conf.py，但我想知道是否有人解决了这个问题。

如何交叉引用 reStructuredText 文档中的索引项？

例如，我如何交叉引用 SectionB：

我尝试在引用中使用索引标签，例如：

但这不起作用。

继去年关于文档的问题之后，我现在想开始尝试基于 Python 的Sphinx来整理我一直在研究的 PHP CMS 的开发人员文档。

我不想在我的工作站上本地设置 Python，而是想从一开始就在可公开访问的 Web 服务器上运行它。我可以访问的所有网络托管包都在 LAMP 堆栈上运行，我不愿意购买基于 Python 的托管。我对 Google App Engine 很感兴趣，他们提供的免费配额会为我做一百倍，即使没有，他们的定价看起来也很合理。

现在我对 Python 的了解为零——让 Sphinx 工作将是我第一次接触它——而且时间很少。据我了解，App Engine 提供的平台库和 Python 库与标准 Python 库非常兼容，但并不完全相同。

所以我的问题是：

• Sphinx 可以在 App Engine 上运行吗？

• 在 App Engine 上安装 Sphinx 是否像在普通 Python 安装之上安装它一样简单？或者，App Engine 的环境是否需要对我当前的 Python 水平无法在合理时间内执行的源代码进行调整？

• 我应该先在本地服务器上安装 Sphinx 和“普通”Python 堆栈吗？

• 有人知道任何有用的操作方法、教程或其他资源吗？

我有一些 .rst 文件，我使用标准 sphinx 转换器将它们转换为 .tex 文件。

在某些 .rst 中，我有特殊宽度的表格，例如：

生成的 .tex 始终包含如下表格：

因此，列宽丢失。

将 rst 转换为乳胶时如何保留列宽？

我也使用逗号分隔符，

但它不起作用..也许我使用了一个坏转换器？你推荐什么转换器？