How do I correctly start using .readthedocs.yml - read-the-docs

Question

I have a basic ReadTheDocs repository. As per the advice of the build page, I sought to use a .readthedocs.yml to configure it:
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.
I added a basic .readthedocs.yml:
version: 2
sphinx:
builder: dirhtml
fail_on_warning: true
and got a build failure:
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.
This was surprising as it seemed contrary to the guidance in the admin dashboard at https://readthedocs.org/dashboard/PROJECTNAME/advanced/ which led me to assume that I could set whatever I liked in the admin dashboard, but it would be overridden by my .readthedocs.yml (which is the behaviour I expected and wanted):
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.
I updated the setting in the admin dashboard to match the .readthedocs.yml and then got a build error:
Sphinx error:
master file /home/docs/checkouts/readthedocs.org/user_builds/PROJECT_NAME/checkouts/latest/source/contents.rst not found
which looks like https://github.com/readthedocs/readthedocs.org/issues/2569 (RTD not finding Sphinx configuration) - but it's not clear why that's happening because prior to adding .readthedocs.yml, the project built just fine.
I'm struggling to model what's actually going on here:
The config file isn't acting as an "overlay" / "override" onto the web settings - as per the first error, some forms of disagreement are a build failure
It's almost like if the config file exists, the web config is ignored - this would explain the contents.rst issue arising, but this isn't consistent with the first error
Adding a python.install entry to .readthedocs.yml eventually got the site building, but it's still not clear to me if I'm generally doing the right thing, and/or how successful future config changes will be.

Answer 1

The reason you're getting the error is that the sphinx version you're using locally doesn't match with the version readthedocs is using at the time you initiated the build process.
See here: You can use a requirements.txt file to use the same version of sphinx you use locally. I had the same issue. I've solved it by simply adding my version Sphinx==3.1.2
Also, I added a .readthedocs.yml file in my project directory where docs/ resides, pointing to where the conf.py because
I was using an extension sphinxcontrib.napoleon which readthedocs build process fails to recognize.
Wanted readthedocsbuild process to use a specific version on 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
and added all the dependencies needed to generate the documentation in 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