问题标签 [read-the-docs]

我正在开发一个专有的内部应用程序，我想在某处构建和托管文档。由于它是专有的，我不能使用 readthedocs 的公共版本。是否有http://readthedocs.org的付费或私人版本？

我可以使用 Sphinx 在本地自动生成我的项目的 API 文档，但是当我尝试使用 ReadTheDocs 时遇到了麻烦。当 ReadTheDocs 构建文档时，API 页面都是空白的（例如，参见这个）。读完这篇博文后，我意识到解决方案是模拟 numpy 和 matplotlib 之类的东西。所以我将以下行添加到我的conf.py

添加后，由于以下两个 Sphinx 问题，我无法在本地或 ReadTheDocs 上构建 API 文档。

问题 #1：

当我构建文档时，出现以下错误。

我已经确认这个错误来自简单地做matplotlib.__version__.split("."). 我无法弄清楚如何快速解决此问题，因此我将其注释掉。

问题 #2：

现在，我在构建文档时收到以下错误。

如果我注释掉有问题的行 ( _mpl.rcParams['backend'] = 'Qt4Agg')，我会在下一行得到相同的错误，因为我的params模块充满了对matplotlib.rcParams字典的分配。

这两个问题看起来都很难解决。有没有更好的办法？如果没有，我应该如何解决问题 #1 和 #2？

从阅读本文来看，似乎有一种解决方法可以将字典与模拟一起使用。我应该寻找一个类似的解决方案来使用像来自的字符串一样基本的东西matplotlib.__version__吗？

如果有帮助，github 上的代码在这里。

我有一个包含各种文件夹的目录，每个文件夹中都有 matlab 源文件。其中一些文件夹具有包含 matlab 源文件的子文件夹。

如何使用 Sphinx 创建 TOC 树以嵌套方式包含子文件夹？

例如，当Main-Directory包含conf.py、index.rst、 以及moduleslist.rst以下文件夹结构时：

使用此index.rst文件：

这个moduleslist.rst文件：

但这不包括其中的子文件夹Folder2.1和文件。我尝试添加Folder2/index，index.rst其中Folder2/index.rst包含 的自动模块Folder2.1，其中不包括ghi.m.

如何让 Sphinx 在其 TOC 树中显示嵌套的子文件夹？

我发现我在 readthedocs.org 上托管的最新版本的网站 eswp3.org的搜索功能不再起作用。我使用 python-sphinx html 主题sphinx_rtd_theme的默认搜索功能。我使用默认的 makefile 来构建 html 文件。

一些可能的错误原因调查：

• 网站版本 v1.1 和网站版本 v1.0 的搜索字段已损坏。
• 在网站版本 V0.1 中，搜索字段正在工作。（版本可以通过网站左下角的字段进行切换。）
• 重建网站源 v1.0后，在本地文件系统上，v1.0 的搜索字段不起作用，v0.1 的搜索字段起作用。
• 比较网站源 v1.0 和 v0.1 会导致以下差异：

到差异屏幕截图

• 我检查了 conf.py 中的差异，但没有发现关键差异。
• 我删除了 _build/html 中的文件，并make html在我的本地文件系统的根目录 eswp3/ 中使用 python-sphinx 默认 make 目标重建了这些文件。没有打印关于索引的问题。
• 不幸的是，生成版本中的搜索字段也不起作用。

我错过了什么？我是否必须考虑不同构建中使用的 python-sphinx 版本的可能差异？

提前非常感谢。

我最近添加了 blowdrycss 的 sphinx 文档来阅读文档。

我想覆盖readthedocs上的 layout.html 模板。我当前的模板覆盖在 上运行良好localhost，但在 readthedocs 上运行良好。该项目使用扩展了基本主题的雪花石膏主题。

项目目录结构可以看这里

相关部分是：

模板设置conf.py：

layout.html 的内容：

如何覆盖layout.htmlreadthedocs 上的模板？

更新 我也试过：

相关部分是：

模板设置conf.py：

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

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

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

所以，我想要的目录结构如下：

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

可以/应该通过index.rst在modules目录中放置另一个来以某种方式实现吗？

我已经构建了一个容器化的 readthedocs 安装。到目前为止对它很满意，但是我看到它在项目页面上构建了短 url。不幸的是，短网址在 DNS 中不存在，所以不要链接到任何地方。例如，它们显示为<project>.readthedocs.mydomain.com

浏览管理门户和 rtd 文档，我看不到它们的配置位置，也没有找到将 shorturl 修改为其他格式或禁用 shorturl 的方法。有没有其他人遇到过这个问题，也许有他们可以分享的解决方案？

非常感谢

结构

项目结构如下：

• index.rst

  /li>

• group1.rst

  /li>

渲染到（点击Group1->后Subgroup2）：

如您所见，它打开Group1页面并链接到Subgroup2部分。

想

我想在左侧有相同的内容（打开Group1并Subgroup2选择），但在右侧我只想看到Subgroup2页面（没有Subgroup1内容的页面）。

即有文件group1/subgroup1.rst：

渲染到：

如何实现？这是一个深度为 2 的简单示例，那么深度 3-4 呢？

我了解在使用Sphinx时可以使用TOC 指令编辑目录（即排序元素、使用子节点等）。

使用 Markdown 时可以实现这一点吗？

编辑徽章现在也在 GitHub 上显示为绿色。会不会和 GitHub 做的缓存有关？

编辑 2哦，它又是红色的。

ReadTheDocs 项目中的徽章是绿色的。

但是，当我将徽章 HTML 或 Markdown 代码粘贴到我的 GitHub 存储库的 README.md文件中时，它总是显示为红色。

• 我已经检查了大约 20 次，现在徽章代码是正确的。它在其他地方显示为绿色（例如，当我将徽章代码粘贴到http://www.ctrlshift.net/project/markdowneditor/时）。
• 我也用另一个互联网浏览器和我的手机打开了 GitHub 页面，但它仍然是红色的，所以这不是客户端缓存问题。
• 当我直接去徽章图像源时，我也得到一个绿色徽章。

到底怎么回事？

自述文件.md