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

【问题标题】：How do I correctly start using .readthedocs.yml如何正确开始使用 .readthedocs.yml
【发布时间】：2020-02-23 17:17:14
【问题描述】：

我有一个基本的 ReadTheDocs 存储库。根据构建页面的建议，我试图使用.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 最终得到了网站建设，但我仍然不清楚我是否在做正确的事情，和/或未来的配置更改会有多成功。

【问题讨论】：

标签： read-the-docs

【解决方案1】：

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

请看这里：You can use a requirements.txt file to use the same version of sphinx you use locally。我遇到过同样的问题。我通过添加我的版本Sphinx==3.1.2

解决了它

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

我使用了一个扩展 sphinxcontrib.napoleon，而 readthedocs 构建过程无法识别。
希望 readthedocsbuild 进程在 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

【讨论】：