How do I get Sphinx to generate 'contents.rst'?

Question

The Sphinx templates I use (for example sphninxdoc or sphinx13) have a link to a 'contents.rst' file; however, though this file is documented as "special", I don't see a way to generate it.

Is there a way to get Sphinx to generate 'contents.rst' automatically, or do I need to generate it manually?

Answer 1

When I came to this page, I needed to fix the .readthedocs.yml. My sphinx configuration path was missing the "source" part:

# Build documentation in the docs/ directory with Sphinx
sphinx:
  configuration: docs/source/conf.py

Within the config, I have

# The master toctree document.
master_doc = 'index'

Answer 2

The "special" contents.rst file that is mentioned in the question is not generated automatically. It is written like any other reST file and is stored in the Python repository: https://github.com/python/cpython/blob/master/Doc/contents.rst.

The Python documentation main page at http://docs.python.org/release/2.7/index.html has a Complete Table of Contents link that points to contents.html, which is built from contents.rst.

The source for the Sphinx documentation includes a similar contents.rst: https://github.com/sphinx-doc/sphinx/blob/master/doc/contents.rst.