标签: read-the-docs

目前，我可以找到获取 readthedocs.org 使用的当前设计资产的唯一方法是安装完整的主题，并构建它，这需要 SASS 等。

我只想获得一组静态文件，让我可以在本地查看我的构建在 readthedocs 上的样子。有没有办法在不通过上述链接自己构建资产的情况下做到这一点？目标是让新手可以轻松地为文档做出贡献。

我有一个python-3项目，它使用plot-directive 动态生成和嵌入 matplotlib 的图表，我正在使用ReadTheDocs自动生成项目的文档。
plot-directive在 python-2 中确实可以正常工作，但它目前在 python-3 中失败。

具体来说，我在 RTD 日志中遇到的故障是：

构建标准错误

html
-----

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/wltp/envs/master/lib/python3.4/site-packages/sphinx/application.py", line 325, in setup_extension
    mod = __import__(extension, None, None, ['setup'])
ImportError: No module named 'matplotlib'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/wltp/envs/master/lib/python3.4/site-packages/sphinx/cmdline.py", line 253, in main
    warningiserror, tags, verbosity, parallel)
  File "/home/docs/checkouts/readthedocs.org/user_builds/wltp/envs/master/lib/python3.4/site-packages/sphinx/application.py", line 119, in __init__
    self.setup_extension(extension)
  File "/home/docs/checkouts/readthedocs.org/user_builds/wltp/envs/master/lib/python3.4/site-packages/sphinx/application.py", …

我想在readthedocs.org中发布我的项目https://bitbucket.org/oaltun/opn的文档.

构建失败.日志https://readthedocs.org/builds/opn/2247789/中显示了不同的错误 ,但第一个是"没有名为sip的模块".

pyqt需要sip,这是项目所需要的.

通常在这种情况下,据我所知,你会在setup.py中添加缺少的包,并检查readthedocs.org选项以创建virtualenv.我选中这个框来创建一个virtualenv.但是我不能在setup.py中添加sip或pyqt.

问题是pyqt&sip不使用setuptools,因此无法通过pip安装.所以你不能将它们添加到setup.py(即使在我的本地机器上也会失败).

在我的本地环境中,我使用(ana)conda安装pyqt.但我认为readthedocs.org使用pip来调用依赖项.

那么,我怎么能让我的virtualenv包括sip？

我想使用 ReadTheDocs 来托管我的 Sphinx 文档。该项目托管在github上。我可以很好地连接到它。

我的特殊之处在于该项目包含 2 个 Sphinx 文档（例如程序员手册和用户手册）。ReadTheDocs 似乎正在检测两者（有两个 conf.py）并构建两者。但是，在显示它们时，它仅显示其中一个的 html，据我所知，按字母顺序排列第一个。

所以我的问题是：

1. 如果两者都已建成，您如何才能看到另一个？

2. 有没有办法使用“子项目”来指定每个 conf.py 的路径，从而为每个文档/手册提供清晰的 URL？那将是理想的解决方案。

我有开源我的一些代码，但文档将无法正确ReadTheDocs尽管预期与Makefile文件创建通过努力建立sphinx-quickstart和make html本地。任何人都可以就我在 RTD 集成方面做错了什么提出建议吗？

我已经阅读了有关可能使用 RTD 高级设置在 virtualenv 中构建模块的信息，但这不起作用，因为我有 scipy 作为要求，并且由于没有可用的 BLAS 库而导致构建失败（对于每个构建来说，这也是一项不必要的冗长任务的文档）。

sphinx.ext.autodoc 和 sphinx.ext.napoleon（用于 Google 风格的文档字符串）都包括在内。本地我只是跑dev-scripts/api-docs.sh这一次创建docs/source/bnol.rst和docs/source/modules.rst。然后使用标准的 Makefile（在 git repo 中忽略）按预期构建文档。

• 包含软件包的GitHub 存储库/bnol/
• 狮身人面像配置文件
• RTD 托管的文档未正确构建

编辑：我发现这个FAQ 详细说明了 RTD 上的构建过程，并在sphinx-build本地使用了相同的过程，它按预期工作。我正在搜索 RTD 日志以查找错误，但目前还没有什么值得注意的。

我正在使用 Sphinx 文档的 Read the Docs 主题创建文档。我试图将整个网页居中 - 正文和左侧导航栏，这样如果窗口的宽度增加，左侧和右侧的边距也会增加。目前，所有内容都固定在屏幕的左侧。

我对 css 样式表做了一些实验，发现通过用“margin:0 auto”替换“margin:0”的所有实例，身体会转移到中心对齐。但是，导航栏仍然锁定在屏幕的左侧。关于如何做到这一点的任何建议？我对 html 和 css 的经验很少。如果需要，我可以上传文件。

我安装了read-the-docs，以从需要用户/密码验证的私有git存储库上的项目开始生成文档。

手动导入项目时，如何输入用户名和密码以允许文档阅读者克隆存储库？

非常感谢，马克斯

我正在尝试添加阅读文档以查看我们的 github 托管项目的文档。该项目是Calour——一个用于微生物组实验的交互式热图分析程序。

我们对这个项目有很多要求——有些是可以通过 conda 安装的（比如 numpy、scipy 等），有些需要 pip 安装。

对于 sphinx 文档，我们需要导入 calour 模块本身，它依赖于所有这些依赖项。

使用 readthedocs.yml 中的 conda: 部分，我们设法安装了 conda 和 pip 依赖项，但是，当我们尝试使用 python 部分“ python.setup_py_install: true ”标志时，读取文档不会创建 conda 环境，而是创建一个没有安装 conda 的虚拟环境。

有没有办法在 conda 环境中运行 setup.py？

我已经在使用自定义CSS来覆盖使用的主题样式

def setup(app):
    app.add_css_file('custom.css')

这很好。什么其他的应用程序。功能可用吗？我找不到任何文档。

我正在寻找功能来替代收藏夹图标。

我有一个项目，我通过标签管理版本git。然后，我使用setuptools_scm在 my 中获取此信息setup.py，并生成一个文件 ( _version.py)，该文件在生成 的轮子时包含在内pip。

此文件未被跟踪，git因为：

1. 它具有可以通过以下方式收集的相同信息git
2. 这会造成一个循环的情况，造轮子会修改版本，从而改变源，并生成一个新版本

现在，当我构建文档时，从中获取此版本变得很自然_version.py，并且这一切在本地运行良好。

但是，当我尝试在 ReadTheDocs 中执行此操作时，文档的构建失败，因为_version.py未由 跟踪git，因此 ReadTheDocs 在从存储库获取源代码时找不到它。

编辑：我尝试使用重复中提出的方法，该方法与文档中指示的方法相同setuptools_scm，即使用docs/conf.py：

from pkg_resources import get_distribution
__version__ = get_distribution('numeral').version
... # I use __version__ to define Sphinx variables

但我得到：

pkg_resources.DistributionNotFound：未找到“数字”分布，并且是应用程序所需的

（同样，在本地构建文档可以正常工作。）

如何解决这个问题而不需要在两个地方维护版本号？