标签: read-the-docs

我的理解是新的Read The Docs主题从toctree生成侧边栏,深度为2.我的文档相对较深,深度为2并不足以使其有用.如何增加此限制,或者最好将其完全删除？

如果这不合理,我怎样才能使用本地ToC而不是全局toctree？

我按照阅读文档中的说明进行操作，但出现此错误：

bash Sphinx错误：未找到主文件/home/docs/checkouts/readthedocs.org/user_builds/mybinders/checkouts/latest/docs/source/contents.rst

是否需要阅读docs yaml文件？

我对这件事情全新.花了一整天试图找出"最常用"的方法.我想要实现的是像readthedocs.org,但对于私人客户(和专有项目)

几乎所有的常见问题解答,博客文章,howtos等都在描述如何使用GitHub页面使用主机(发布)文档,或者使用readthedocs.org(.com)

我试图在本地使用Sphinx(NB:不是 "Sphinx搜索"),我可以很容易地构建一个示例演示文档,但我并不完全理解如何托管"可搜索"的解决方案,就像它一样适用于http://www.sphinx-doc.org(似乎它使用readthedocs.org作为搜索后端)

我试图在本地部署readthedocs.org,但是

1. "搜索"不起作用(没人监听127.0.0.1:9200)
2. 我无法构建任何文档(找不到版本或找不到项目)
3. 我无法从我的私人存储库添加项目(ssh :)

(注意:我在Windows上尝试它,这可能解释1-2项,但不是3,我相信)

到目前为止感觉我的想法已经用完了......

任何建议将受到高度赞赏!

我有一个托管在 Github 上的 Python 包，名为Spike2py。我已经使用 Sphinx 和 .rst 文件准备了我的文档。这些文件托管在 GitHub上。我能够make html在本地成功运行并获得所需的输出。也就是说，文档的参考指南部分包含使用我包含在代码中的文档字符串自动生成的 API，并使用对autoclass和autofunction( reference_guide.rst ) 的调用进行引用。

例如，当我在本地渲染时，参考指南的第一部分如下所示：

然而，当文档呈现在readthedocs（参见此处）上时，参考指南不包含提取的文档字符串；只是 .rst 文件中找到的标头。

预期行为

我希望 readthedocs 上呈现的文档与本地呈现的文档相同。然而，这并没有发生。

通过查看此处，我已确认当前版本的文档中的 readthedocs 上提供的版本。

但是，当我尝试下载文档的 PDF 或 HTML 版本时，参考指南不包含文档字符串。

其他信息

根据 readthedocs文档，本地构建不应推送到 GitHub；仅源文件。

这与这个问题有些相关，但我无法使建议的解决方案发挥作用。

更新 我遵循了 Steve Piercy 推荐的解决方案，这解决了部分问题。我添加了一个docs/requirements.txt文件以及一个.readthedocs.yml文件。

接下来我注意到构建使用的是 Python 3.7.9。鉴于我使用的是 Python >= 3.8 的类型提示，我必须在文件中指定 Python 的版本.readthedocs.yml。

然后我被 RTD 构建困住了，告诉我它找不到我的 index.rst 文件。 …

我正在尝试使用ReadTheDocs记录Python项目.最初,构建过程会在以下情况下死亡:

from osgeo import gdal, osr

我已经阅读了rtd faq并使用了mock来为我提供麻烦的osgeo模块.现在构建过程使它通过导入但是窒息:

from osgeo.gdalconst import * 

有了这个相当无益的错误:

RuntimeError: sys.path must be a list of directory names

我完全不习惯使用mock,但我认为问题在于它osgeo是一个模拟模块,因此没有子模块gdalconst.我该如何解决这个问题？有没有办法模拟子模块？

我为我的项目设置了Sphinx文档,并希望提取源文件的doc字符串并将它们嵌入到最终文档中.不幸的是,Sphinx不支持源文件的语言(VHDL).VHDL似乎没有Sphinx域.

所以我的想法如下:

• 在Sphinx之前进入Sphinx运行并执行一些Python代码
• Python代码从每个源文件(最顶层的多行注释块)中提取文本块,并为每个源文件组装一个reST文件,包括此注释块和一些其他reST标记.
• 所有源文件都列在a中index.rst,以生成适当的.. toctree::指令.
• 每个源代码目录递归地完成文本提取和转换.

所以主要的问题是:如何挂钩到Spinx？

或者我应该导入并运行我自己的配置conf.py？

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
from my_preprocessor import my_proc
proc = my_proc()
proc.run()
#
# Test documentation build configuration file, created by
# sphinx-quickstart on Tue May 24 11:28:20 2016.
# ....

我无法修改构建过程文件:Makefile并且make.bat,因为真正的构建过程在ReadTheDocs.org上运行.RTD仅执行conf.py.

我正在尝试使用以下内容将一个交互式图形(保存为html文件)嵌入到reStructuredText文档中iframe:

.. raw:: html

    <iframe src="filename.html" height="345px" width="100%"></iframe>

html文件与我的.rst文件位于同一目录中,但图形不显示,我收到file could not be found错误.

但是,如果我将外部html文件粘贴到_build/html目录中,则图表显示正常.如何正确嵌入此html文件,以便在我自动嵌入图形时make html？

我想要的东西的工作实例.

我考虑的是：

• github 提供 github 页面以在我的master分支或专用gh-pages分支上的文件夹中托管文档，但这意味着提交构建工件
• 我也可以readthedocs通过 webhooks 为我构建和托管文档，但这意味着在我尝试整合与我的项目相关的所有内容的时间点学习如何配置 Yet Another Toolgithub-actions

我已经有一个对我有用的文档构建过程（sphinx用作构建器）并且我也可以在本地测试，所以我宁愿只是利用它。它设置了所有规则并html在工件中放置了一些静态- 它只是不会在任何地方提供。在工作流程中处理它，我的项目的所有其他部署配置都存在，感觉比将它分散在不同的工具或 github 特定选项中感觉更好。

市场上是否已经有一项行动可以让我做这样的事情？

name: CI
on: [push]
jobs:

  ...  # do stuff like building my-project-v1.2.3.whl, testing, etc.

  release_docs:
    steps:
      - uses: actions/sphinx-to-pages@v1  # I wish this existed
        with:
          dependencies:
            - some-sphinx-extension
            - dist/my-project*.whl
          apidoc_args:
            - "--no-toc"
            - "--module-first"
            - "-o docs/autodoc"
            - "src/my-project"
          build-args:
            - "docs"
            - "public"  # the content of this folder will then …

这通过运行 readthedocs 主题的 sphinx 在本地发生，它也发生在 readthedocs.io 中。

我添加了一个 svg 徽标（实际上它只是从他们的站点复制下载的 rtd logo.svg 以进行测试）。

我已将设置添加到conf.py并且 html 构建正常。

html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
html_logo = 'logo.svg'
html_theme_options = {
    'logo_only': True,
    'display_version': False,
}

如果我在 Firefox 中检查徽标类，它被设置为“自动”，如果我以 px 为单位添加宽度，则会出现徽标。

我觉得好像我在 conf.py 文件中缺少关于 readthedocs 主题的配置的一些东西？

当然，我不必手动修改 CSS：在查看其源代码时，我在 Readthedocs.io 站点中没有看到更改 CSS 的迹象。

我正在寻找一个优雅的解决方案 - 我不希望更新 readthedocs 主题来破坏我的网站，因为我一直在覆盖主题的 CSS。

问题

在 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 …