标签: read-the-docs

我正在尝试使用sphinx来记录文档的多个"级别",例如:

• Api参考
• 手册
• 教程
• 等等.

我们的想法是,目录栏显示在侧栏上,相对于您所在的部分.因此,当您在主索引上时,它只显示上面提到的部分.当你进入eg."手动"它显示了该部分特定的不同ToC,以及返回主ToC的方法.

我一直试图弄清楚如何让它在Sphinx中工作而不会入侵它,但到目前为止还不能找到方法.文件夹结构已经反映了不同的部分(即所有"手动"文档存储在_source/manual下),我尝试在每个目录中放置单独的索引文件,但似乎toctree功能只查看主索引文件.

我正在使用"readthedocs"主题,我正在特别关注的代码是https://github.com/snide/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/layout.html#L93

谁能告诉我如何使用Sphinx添加像这样的ToC？

谢谢

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

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

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

    Folder1
        abc.m
        def.m
    Folder2
        Folder2.1
            ghi.m
        jkl.m

用这个index.rst文件:

.. toctree::
    :maxdepth: 1

    moduleslist

和这个moduleslist.rst文件:

.. toctree::
    :maxdepth: 2

Folder1
=========
.. automodule:: Folder1
:members:

Folder2
=========
.. automodule:: Folder2
    :members:

但是这不包括子文件夹Folder2.1和文件.我曾尝试加入Folder2/index的index.rst,与Folder2/index.rst载有automodule Folder2.1,其中不包括的文件ghi.m.

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

我正在使用sphinx和RST将一些技术文档生成为 HTML，并且在将本地 PDF 引用用作超链接时遇到问题。我见过人们:download:用来链接到本地​​ PDF，但我将 PDF 嵌入到/docs目录中以供参考。我不喜欢，:download:因为它不会在浏览器中内嵌显示 PDF，这需要代表用户执行额外的步骤才能使用。

sphinx-build -b html除非在config.pyhookhtml_static_path或html_extra_path-中指定，否则不会复制任何文件，即使这样，它们也会被放到root目录或_static文件夹中。

是否有在 sphinx 中嵌入链接二进制文件的建议方法，或者这是一种不好的做法？通常，这些链接指向未托管在其他任何地方的幻灯片或设计图。

链接 PDF 的示例 RST

.. important:: View the agile course on scrum basics

    - View `these slides to dive deeper into Agile Basics <docs/agile-101.pdf>`_. 

我正在使用他们的主题在 ReadTheDocs 上使用 Sphinx 创建我的文档。构建过程会生成一个 genindex.html 文件，可以通过以下方式引用：

Link to the :ref:`genindex` page.

这创造了：

链接到索引页面。

我无法添加genindex到我的 toctree，例如像这样：

.. toctree:

   foo
   bar
   genindex

因为它是一个自动生成的文件，在渲染时不存在。此外，Sphinx 期望 genindex 是一个名为genindex.rst.

如何将其添加到我的 ToC/导航中？

问题：

我一直在与Read the Docs斗争。导入的模块与 I/O 交互，因此文档不包含任何文本。 但是构建不会失败。

尝试的解决方案：

我正在尝试在 doc/conf.py 中使用mock或MagicMock但它不起作用。

所需的解决方案

基本上，我想mock整个导入。所以RTD并没有尝试运行任何代码。只需从 DocStrings 生成文档。

我只是想要一个模块的mock 所有元素。在类，函数和变量。 任何带有 DocString 的东西。

目前我必须在 virtualenv 中安装项目，以满足导入。如果没有必要，我想避免这种情况。现在......如果我不这样做，那么文档也不包含任何文本。 同样，构建不会失败。

细节

例子.py

"""Basic DocSting Comments"""
from external.module import *

foo = module()
foo.connect()
"""
I want this to show up in RTD.
"""

我的具体案例可以在这里找到。

文档/conf.py

from mock import MagicMock

MOCK_MODULES = ['external.module', 'eternal.module.module', 'external.module.module.connect'] …

我正在寻找删除Next和Prev按钮。根据我从文档中读到的内容，这可以通过排除relations.html;来实现。但我不确定如何实现这一目标。

我尝试将以下内容添加到conf.py，没有太多改变

html_sidebars = {'**': ['localtoc.html', 'searchbox.html']}

如果有任何相关性，我正在使用 ReadTheDocs 主题。

我一直在构建一个具有许多不同功能的Python模块.

我正在使用Sphinx和readthedocs来提供文档.我已经取得了不错的进展,但目前我有一个庞大的页面,提供了我所有功能的文档(按字母顺序排列).

我查看了其他项目,每个项目都有一个单独的页面.通过查看源代码,我发现为每个文件创建了一个单独的.rst文件.我假设这是自动完成的,这个关于生成autodoc摘要的页面似乎正在描述其中的一些,但我无法理解它.

sphinx-apidoc 有一个选项(-e)为每个模块创建一个页面,但我想为每个函数创建一个页面.

如何使用Sphinx为每个函数自动生成单独的页面？

附加信息

要为下面的其中一个答案添加信息,我将以下内容放入我的EoN.rst文件中,该文件位于子目录中docs.

EON documentation
=================

.. automodule:: ../EoN
   :members:

.. currentmodule:: ../EoN

.. autosummary::
   :toctree: functions

   fast_SIR
   fast_SIS

我收到错误消息

$ sphinx-autogen -o docs/generated docs/*.rst

[autosummary]生成autosummary:docs/index.rst,docs/methods.rst,docs/quickstart.rst

[autosummary]写入docs/generated

警告:[autosummary]无法导入u'fast_SIR':没有名为fast_SIR的模块

警告:[autosummary]无法导入u'fast_SIS':没有名为fast_SIS的模块

fast_SIS并fast_SIR坐在里面../EoN.py

我有一个基本的 ReadTheDocs 存储库。根据构建页面的建议，我试图使用 a.readthedocs.yml来配置它：

配置您的文档版本！将 .readthedocs.yml 文件添加到项目中是配置文档构建的推荐方法。您可以声明依赖项、设置子模块以及许多其他出色的功能。

我添加了一个基本的.readthedocs.yml：

version: 2

sphinx:
  builder: dirhtml
  fail_on_warning: true

并遇到构建失败：

您的项目配置有问题。无效的“sphinx.builder”：.readthedocs.yml：您的项目在管理仪表板中配置为“Sphinx Html”，但您的“sphinx.builder”密钥不匹配。

这是令人惊讶的，因为它似乎与https://readthedocs.org/dashboard/PROJECTNAME/advanced/上的管理仪表板中的指导相反，这使我假设我可以在管理仪表板中设置我喜欢的任何内容，但它会是被我的覆盖.readthedocs.yml（这是我期望和想要的行为）：

可以使用配置文件来配置这些设置。这是设置项目的推荐方法。配置文件中的设置会覆盖此处列出的设置。

我更新了管理仪表板中的设置以匹配.readthedocs.yml，然后收到构建错误：

Sphinx error:
master file /home/docs/checkouts/readthedocs.org/user_builds/PROJECT_NAME/checkouts/latest/source/contents.rst not found

看起来像https://github.com/readthedocs/readthedocs.org/issues/2569（RTD 找不到 Sphinx 配置） - 但不清楚为什么会发生这种情况，因为在添加之前.readthedocs.yml，项目构建得很好。

我正在努力模拟这里实际发生的情况：

• 配置文件不充当网络设置的“覆盖”/“覆盖” - 根据第一个错误，某些形式的分歧会导致构建失败
• 这几乎就像如果配置文件存在，Web 配置就会被忽略 - 这可以解释contents.rst出现的问题，但这与第一个错误不一致

添加一个python.install条目.readthedocs.yml最终可以构建站点，但我仍然不清楚我通常是否在做正确的事情，和/或未来的配置更改会有多成功。

几周前，我制作了一个我正在私有的 RTD 文档版本，因为该版本仍处于 alpha 状态。现在是再次公开文档的时候了，因为我们正在准备发布该版本

然而，出于某种原因，现在似乎不可能将该私人版本切换回公共版本。

以下是您可以看到 5.0 标记为私有的版本列表：

但是，在编辑 5.0 时，无法再次将其设为公开。这是该编辑屏幕的屏幕截图：

我尝试更改“活动”和“隐藏”，甚至擦除了 5.0，并浏览了完整的管理菜单，谷歌搜索，并阅读 RTD 文档以找出如何再次公开该版本，但没有成功。

如何将 5.0 分支切换为 public 并更改版本指向的分支？

问题

在 readthedocs.io 网络界面上单击“构建”时，我无法成功构建我的文档，但它在我的本地机器上构建得很好。为了测试这是一个环境问题，我创建了一个虚拟环境：

conda create virtualenv -n venv
conda env export -n venv
source activate venv

然后我将我的 requirements.txt 文件安装为：

pip install -r requirements.txt

然后跑了

make clean html

在虚拟环境和在线 buildthedocs 中，我收到错误消息：

Notebook error:
PandocMissing in ex_degassing.ipynb:
Pandoc wasn't found.
Please check that pandoc is installed:
http://pandoc.org/installing.html
make: *** [html] Error 2

我已经搜索并搜索了一个解决方案，但我最好的猜测是 pandoc 没有通过 pip 安装，即使它在 requirements.txt 文件中。我还尝试通过在我的 requirements.txt 文件中替换pandocwith来告诉它从源代码构建git+git://github.com/jgm/pandoc#egg=pandoc，但这不起作用（请参阅下文了解我的文件的外观）。我可以轻松地在本地机器上安装 pandoc，但无法通过我的虚拟环境或 readthedocs 中的 requirements.txt 文件进行安装。

我的一些文件

这是我的requirements.txt文件：

sphinx>=1.4
sphinx_rtd_theme
ipykernel
nbsphinx
pandas
pandoc
numpy …