如何正确开始使用 .readthedocs.yml

Question

我有一个基本的 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最终可以构建站点，但我仍然不清楚我通常是否在做正确的事情，和/或未来的配置更改会有多成功。

Answer 1

您收到错误的原因是您本地使用的 sphinx 版本与readthedocs您启动构建过程时使用的版本不匹配。

请参阅此处：您可以使用requirements.txt文件来使用与本地使用的相同版本的sphinx。我遇到过同样的问题。我通过简单地添加我的版本解决了这个问题Sphinx==3.1.2

另外，我.readthedocs.yml在项目所在目录中添加了一个文件docs/，指向conf.py因为

1. sphinxcontrib.napoleon我正在使用构建readthedocs过程无法识别的扩展。
2. 希望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/requirements.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