This doesn't look to be a problem with RTD, so I'm going to close it. The error message states it is looking for a contents.rst, which doesn't exist. If you don't specify otherwise, Sphinx's default master_doc setting is contents. If you'd like to use index instead, you'll need to create a configuration file. I suggest you first explore http://www.sphinx-doc.org/en/1.5.1/tutorial.html as you should be getting the same errors locally, it might be easier to learn Sphinx this way.

Encountered the same problem here.

I'm using sphinx 2.0.1. The generated structure by sphinx-quickstart command is built into html documentation successfully in my environment, while in readthedocs.org there occurs "contents.rst not found" error.

I finally found it works by adding the following line in conf.py to explicitly assign the master document:

master_doc = 'index'

I guess this issue is caused by the conflicts of the default sphinx version in readthedocs and the local environment.

I just record this solution here in case someone like me will be confused by this issue and have no idea about how to deal with it.

You can use a requirements.txt file to use the same version of sphinx you use locally https://docs.readthedocs.io/en/stable/guides/specifying-dependencies.html

Encountered the same problem here.

I'm using sphinx 2.0.1. The generated structure by sphinx-quickstart command is built into html documentation successfully in my environment, while in readthedocs.org there occurs "contents.rst not found" error.

I finally found it works by adding the following line in conf.py to explicitly assign the master document:

master_doc = 'index'

I guess this issue is caused by the conflicts of the default sphinx version in readthedocs and the local environment.

I just record this solution here in case someone like me will be confused by this issue and have no idea about how to deal with it.

Worked for me !! Thanks

master_doc = 'index'

I have been struggling with this issue for hours. thank you for sharing the answer.

You can use a requirements.txt file to use the same version of sphinx you use locally https://docs.readthedocs.io/en/stable/guides/specifying-dependencies.html

Currently, RTD installs the following packages before installing packages from the project requirements file:

python -m pip install --upgrade --cache-dir .cache/pip Pygments==2.3.1 setuptools==41.0.1 docutils==0.14 mock==1.0.1 pillow==5.4.1 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.8.1 recommonmark==0.5.0 sphinx<2 sphinx-rtd-theme<0.5 readthedocs-sphinx-ext<1.1 

I do not know why they use such old versions (sphinx<2 for example). If I do not set versions in my requirement file, sphinx version will not be updated and I will get the error contents.rst not found. In my opinion, it seems stupid.

The confusion is well-stated by @adamj-codethink:

I am also seeing this issue after follow the "getting started with sphinx" guide: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html, it seems like a bug with these instructions?

The instructions are fine. The sphinx-quickstart for the latest versions 3.x of Sphinx will create a conf.py without any mentioning of master_doc, thus the default value index is used. It will work fine locally with Sphinx 3.x.

But Read the Docs uses Sphinx 1.8.5 by default and since master_doc isn't specified, another default is used.

Having just onboarded a new user to Read the Docs, this problem came up again: Following standard documentation will land a broken Read the Docs project. Judging from the activity in this thread, it's a problem to many people. For instance the above comment:

I have been struggling with this issue for hours. thank you for sharing the answer.

Solutions?

User has to fix it: Either the user has to add master_doc in their configuration or configure the Read the Docs project to use a newer version of Sphinx. I don't think this is a good way forward for a documentation project 😄

Read the Docs fixing it: We can expect that people are now following guides with the latest version of Sphinx installed locally.

• New projects should be built with Sphinx 3.x as the default
• Read the Docs should force a default master_doc="index" if unset in the supplied docs/conf.py.

Any further thoughts on this?

Read the Docs fixing it: We can expect that people are now following guides with the latest version of Sphinx installed locally.

* New projects should be built with Sphinx 3.x as the default

We are already onboard with this solution. @stsewd already created a PR with the new proposed policy for these external dependencies that Read the Docs relies on, and mentioned that RTD should always install the latest Sphinx version: https://github.com/readthedocs/readthedocs.org/pull/7859/files#diff-1d854732c488780cf89b325277dd80220a7e541647ccf1c18bdc372eb7b1a4d6R71

btw, we already install the latest sphinx version for new projects (created after Oct 20, 2020)

It sounds great that the latest stable version of Sphinx will always be supported and is used for newer projects, that would fix this issue once and for all.

Can the Sphinx version pinned in requirements/pip.txt be clarified?

@benjaminp that dependency is for our intersphinx integration

Thank you @stsewd - I understand now that this is controlled by the Feature flag USE_SPHINX_LATEST and that new projects need to have this Feature flag enabled. I see that this is the new default for readthedocs.org 👍

I think self-hosted deployments have to define the feature flag default themselves in order to avoid this issue?

I think self-hosted deployments have to define the feature flag default themselves in order to avoid this issue?

Yeah, that's correct. You can set the default_true and future_default_true atributes to True so it's aplied to all projects, old and future ones.

master_doc

master_doc = 'source/index'
this worked for me. Thanks for the redirection =)