Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Sphinx error: master file [..]/checkouts/latest/contents.rst not found #2569

Closed
gr2m opened this issue Dec 31, 2016 · 6 comments

Comments

@gr2m
Copy link
Contributor

@gr2m gr2m commented Dec 31, 2016

I’m still new to readthedocs.org and have no experience with either Python nor Sphinx, please excuse me if I’m doing something obviously wrong. I googled the error and have found other builds failing with the same error, but when I looked at their commits that lead to a successful build, the changes didn’t make sense to me.

Details

Expected Result

I expected a new version of docs to be built at http://hoodie-test.readthedocs.io/en/latest/

Actual Result

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/hoodie-test/envs/latest/local/lib/python2.7/site-packages/sphinx/cmdline.py", line 244, in main
    app.build(opts.force_all, filenames)
  File "/home/docs/checkouts/readthedocs.org/user_builds/hoodie-test/envs/latest/local/lib/python2.7/site-packages/sphinx/application.py", line 266, in build
    self.builder.build_update()
  File "/home/docs/checkouts/readthedocs.org/user_builds/hoodie-test/envs/latest/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 251, in build_update
    'out of date' % len(to_build))
  File "/home/docs/checkouts/readthedocs.org/user_builds/hoodie-test/envs/latest/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 265, in build
    self.doctreedir, self.app))
  File "/home/docs/checkouts/readthedocs.org/user_builds/hoodie-test/envs/latest/local/lib/python2.7/site-packages/sphinx/environment.py", line 622, in update
    self.doc2path(config.master_doc))
SphinxError: master file /home/docs/checkouts/readthedocs.org/user_builds/hoodie-test/checkouts/latest/contents.rst not found

Sphinx error:
master file /home/docs/checkouts/readthedocs.org/user_builds/hoodie-test/checkouts/latest/contents.rst not found
@gr2m gr2m changed the title Sphinx error: master file /home/docs/checkouts/readthedocs.org/user_builds/hoodie-test/checkouts/latest/contents.rst not found Sphinx error: master file [..]/checkouts/latest/contents.rst not found Dec 31, 2016
gr2m added a commit to gr2m/hoodie-readthedocs-test that referenced this issue Dec 31, 2016
@agjohnson

This comment has been minimized.

Copy link
Contributor

@agjohnson agjohnson commented Jan 5, 2017

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.

@XinArkh

This comment has been minimized.

Copy link

@XinArkh XinArkh commented Apr 20, 2019

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.

@stsewd

This comment has been minimized.

Copy link
Member

@stsewd stsewd commented Apr 22, 2019

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

willprice added a commit to willprice/flowty that referenced this issue Apr 28, 2019
I get the errror:
```

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/flowty/envs/latest/lib/python3.7/site-packages/sphinx/cmd/build.py", line 304, in build_main
    app.build(args.force_all, filenames)
  File "/home/docs/checkouts/readthedocs.org/user_builds/flowty/envs/latest/lib/python3.7/site-packages/sphinx/application.py", line 341, in build
    self.builder.build_update()
  File "/home/docs/checkouts/readthedocs.org/user_builds/flowty/envs/latest/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 347, in build_update
    len(to_build))
  File "/home/docs/checkouts/readthedocs.org/user_builds/flowty/envs/latest/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 360, in build
    updated_docnames = set(self.read())
  File "/home/docs/checkouts/readthedocs.org/user_builds/flowty/envs/latest/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 472, in read
    self.env.doc2path(self.config.master_doc))
sphinx.errors.SphinxError: master file /home/docs/checkouts/readthedocs.org/user_builds/flowty/checkouts/latest/docs/source/contents.rst not found

Sphinx error:
master file /home/docs/checkouts/readthedocs.org/user_builds/flowty/checkouts/latest/docs/source/contents.rst not found
```

See readthedocs/readthedocs.org#2569
davmlaw added a commit to SACGF/variantgrid_docs that referenced this issue May 7, 2019
@rahulgorai22

This comment has been minimized.

Copy link

@rahulgorai22 rahulgorai22 commented May 15, 2019

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

wilvk added a commit to wilvk/readthedocs.org that referenced this issue Jun 1, 2019
ericholscher added a commit that referenced this issue Jun 6, 2019
fix sphinx startup guide to not to fail on rtd build as per #2569
vdespa pushed a commit to vdespa/gitlab-ci-course-notes that referenced this issue Jun 13, 2019
ctoth added a commit to accessibleapps/sound_lib that referenced this issue Jun 14, 2019
ewjoachim added a commit to peopledoc/procrastinate that referenced this issue Aug 15, 2019
@edyasikpo

This comment has been minimized.

Copy link

@edyasikpo edyasikpo commented Sep 9, 2019

master_doc = 'index'

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

@espdev

This comment has been minimized.

Copy link
Contributor

@espdev espdev commented Sep 12, 2019

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.

oconnor663 added a commit to oconnor663/duct.py that referenced this issue Sep 19, 2019
alahiff added a commit to prominence-eosc/docs-eosc that referenced this issue Sep 27, 2019
teddygroves added a commit to biosustain/Maud that referenced this issue Oct 30, 2019
dzerrenner pushed a commit to dzerrenner/pypyr-scheduler that referenced this issue Nov 15, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
7 participants
You can’t perform that action at this time.