How does readthedocs generate Sphinx HTML from RST without a conf.py? - python-sphinx

Question

I am looking at making changes to an existing project hosted on github and readthedocs. However the generated HTML looks to be built by Sphinx without a conf.py.
$ ls
appendixA.rst chapter11.rst chapter17.rst chapter4.rst html
appendixB.rst chapter12.rst chapter18.rst chapter5.rst images
appendixC.rst chapter13.rst chapter19.rst chapter6.rst index.rst
attribution.rst chapter14.rst chapter2.rst chapter7.rst sandbox
chapter1.rst chapter15.rst chapter20.rst chapter8.rst src
chapter10.rst chapter16.rst chapter3.rst chapter9.rst toc.txt
Note particularly that index.rst exists but conf.py does not. find also shows it is not hiding somewhere else in the project. The generated site on readthedocs works and is consistent with the latest, including some problems seen in the github project, eg Chapter 1 is not indexed properly due to being listed under another name in index.rst.
I am new to Sphinx and readthedocs. In my new local build environment, sphinx doesn't like it at all:
> sphinx-build -b html . html/
Application error:
config directory doesn't contain a conf.py file (.)
That's consistent with the documentation, but not the readthedocs website behaviour. I'm guessing that readthedocs has some fallback behaviour for these cases, probably by generating a simple conf.py from other configuration it holds. However, it makes it hard to reproduce when making changes locally, especially for a project I don't own. If this is the case, I can't find any documentation on this feature. If I am not missing something simple (entirely possible), is there any?
My next step will be to write a new conf.py, and get it to conform to the existing behaviour on a local site. This would be easier if I understood the existing behaviour.
The actual project in question is the Jython book:
https://jython.readthedocs.io/en/latest/
https://github.com/jython/book
Had no luck finding related issues or questions on google, stackoverflow, readthedocs doco or issues. The readthedocs code at https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/projects/models.py seems to have a check for conf.py, too.

Answer 1

Huh, that's interesting that you don't have a conf.py but the docs still built successfully on Date: 2017-10-24T19:18:40.379930Z. I'm just as dumbfounded as you.
Anyway, you can find the conf.py that RTD ends up using under the project's build's raw log file. That might save you some grief. Note that the versions are about 1.5 years old, so you would need to pin versions to try to reproduce it exactly.
cat conf.py
# -*- coding: utf-8 -*-
from recommonmark.parser import CommonMarkParser
extensions = []
templates_path = ['/home/docs/checkouts/readthedocs.org/readthedocs/templates/sphinx', 'templates', '_templates', '.templates']
source_suffix = ['.rst', '.md']
source_parsers = {
'.md': CommonMarkParser,
}
master_doc = 'index'
project = u'jython'
copyright = u'2016'
version = 'latest'
release = 'latest'
exclude_patterns = ['_build']
pygments_style = 'sphinx'
htmlhelp_basename = 'jython'
html_theme = 'sphinx_rtd_theme'
file_insertion_enabled = False
latex_documents = [
('index', 'jython.tex', u'jython Documentation',
u'', 'manual'),
]
###########################################################################
# auto-created readthedocs.org specific configuration #
###########################################################################
#
# The following code was added during an automated build on readthedocs.org
# It is auto created and injected for every build. The result is based on the
# conf.py.tmpl file found in the readthedocs.org codebase:
# https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl
#
import sys
import os.path
from six import string_types
from sphinx import version_info
# Get suffix for proper linking to GitHub
# This is deprecated in Sphinx 1.3+,
# as each page can have its own suffix
if globals().get('source_suffix', False):
if isinstance(source_suffix, string_types):
SUFFIX = source_suffix
else:
SUFFIX = source_suffix[0]
else:
SUFFIX = '.rst'
# Add RTD Static Path. Add to the end because it overwrites previous files.
if not 'html_static_path' in globals():
html_static_path = []
if os.path.exists('_static'):
html_static_path.append('_static')
html_static_path.append('/home/docs/checkouts/readthedocs.org/readthedocs/templates/sphinx/_static')
# Add RTD Theme only if they aren't overriding it already
using_rtd_theme = False
if 'html_theme' in globals():
if html_theme in ['default']:
# Allow people to bail with a hack of having an html_style
if not 'html_style' in globals():
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_style = None
html_theme_options = {}
if 'html_theme_path' in globals():
html_theme_path.append(sphinx_rtd_theme.get_html_theme_path())
else:
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
using_rtd_theme = True
else:
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_style = None
html_theme_options = {}
if 'html_theme_path' in globals():
html_theme_path.append(sphinx_rtd_theme.get_html_theme_path())
else:
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
using_rtd_theme = True
if globals().get('websupport2_base_url', False):
websupport2_base_url = 'https://readthedocs.org/websupport'
if 'http' not in settings.MEDIA_URL:
websupport2_static_url = 'https://media.readthedocs.org/static/'
else:
websupport2_static_url = 'https://media.readthedocs.org//static'
#Add project information to the template context.
context = {
'using_theme': using_rtd_theme,
'html_theme': html_theme,
'current_version': "latest",
'MEDIA_URL': "https://media.readthedocs.org/",
'PRODUCTION_DOMAIN': "readthedocs.org",
'versions': [
("latest", "/en/latest/"),
],
'downloads': [
("pdf", "//readthedocs.org/projects/jython/downloads/pdf/latest/"),
("htmlzip", "//readthedocs.org/projects/jython/downloads/htmlzip/latest/"),
("epub", "//readthedocs.org/projects/jython/downloads/epub/latest/"),
],
'subprojects': [
],
'slug': 'jython',
'name': u'jython',
'rtd_language': u'en',
'canonical_url': 'http://jython.readthedocs.io/en/latest/',
'analytics_code': 'None',
'single_version': False,
'conf_py_path': '/./',
'api_host': 'https://readthedocs.org',
'github_user': 'jython',
'github_repo': 'book',
'github_version': 'master',
'display_github': True,
'bitbucket_user': 'None',
'bitbucket_repo': 'None',
'bitbucket_version': 'master',
'display_bitbucket': False,
'READTHEDOCS': True,
'using_theme': (html_theme == "default"),
'new_theme': (html_theme == "sphinx_rtd_theme"),
'source_suffix': SUFFIX,
'user_analytics_code': '',
'global_analytics_code': 'UA-17997319-1',
'commit': 'cf5cf6de',
}
if 'html_context' in globals():
html_context.update(context)
else:
html_context = context
# Add custom RTD extension
if 'extensions' in globals():
extensions.append("readthedocs_ext.readthedocs")
else:
extensions = ["readthedocs_ext.readthedocs"]