read-the-docs - 我如何正确开始使用 .readthedocs.yml

Question

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

Configure your documentation builds! Adding a .readthedocs.yml file to your project is the recommended way to configure your documentation builds. You can declare dependencies, set up submodules, and many other great features.

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

version: 2

sphinx:
  builder: dirhtml
  fail_on_warning: true

并且构建失败:

Problem in your project's configuration. Invalid "sphinx.builder": .readthedocs.yml: Your project is configured as "Sphinx Html" in your admin dashboard, but your "sphinx.builder" key does not match.

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

These settings can be configured using a configuration file. That's the recommended way to set up your project. Settings in the configuration file override the settings listed here.

我更新了管理仪表板中的设置以匹配 .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最终完成了网站 build ，但我仍然不清楚我是否在做正确的事情，和/或 future 的配置更改将如何成功。

Answer 1

您收到错误的原因是您在本地使用的 sphinx 版本与版本不匹配 readthedocs在您启动构建过程时正在使用。
看这里:You can use a requirements.txt file to use the same version of sphinx you use locally .我遇到过同样的问题。我通过简单地添加我的版本来解决它 Sphinx==3.1.2另外，我添加了一个 .readthedocs.yml文件在我的项目目录中 docs/驻留，指向 conf.py 的位置，因为

我正在使用扩展程序 sphinxcontrib.napoleon其中readthedocs构建过程无法识别。

通缉 readthedocs在 Sphinx 上使用特定版本的构建过程。

# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 1

# Build documentation in the docs/ directory with Sphinx
sphinx:
  configuration: docs/source/conf.py

# Build documentation with MkDocs
#mkdocs:
#  configuration: mkdocs.yml

# Optionally build your docs in additional formats such as PDF
formats:
  - pdf

# Optionally set the version of Python and requirements required to build your docs
python:
  version: 3.7
  install:
    - requirements: docs/requirements.txt
a

并在 docs/requirement.txt 中添加了生成文档所需的所有依赖项

Babel==2.8.0
imagesize==1.2.0
readme-renderer==26.0
Sphinx==3.1.2
sphinx-argparse==0.2.5
sphinx-rtd-theme==0.5.0
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==1.0.3
sphinxcontrib-images==0.9.2
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-napoleon==0.7
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.4