CODEWITHSUNDEEP
python-sphinxread-the-docs
Adam Burke
Adam Burke

Reputation: 864

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

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.

Upvotes: 0

Views: 995

Answers (1)

Steve Piercy
Steve Piercy

Reputation: 15055

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"]

Upvotes: 1

Related Questions