readthedocs 如何在没有 conf.py 的情况下从 RST 生成 Sphinx HTML？

Question

我正在考虑对托管在 github 和 readthedocs 上的现有项目进行更改。然而，生成的 HTML 看起来是由 Sphinx 构建的，没有 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

请特别注意index.rst 存在但conf.py 不存在。 find 还表明它没有隐藏在项目的其他地方。 readthedocs 上生成的站点可以正常工作并且与最新的一致，包括在 github 项目中看到的一些问题，例如第 1 章由于在 index.rst 中以另一个名称列出而未正确索引。

我是 Sphinx 的新手，并且阅读过文档。在我新的本地构建环境中，sphinx 根本不喜欢它：

> sphinx-build -b html . html/

Application error:
config directory doesn't contain a conf.py file (.)

这与文档一致，但与 readthedocs 网站的行为不一致。我猜 readthedocs 对于这些情况有一些后备行为，可能是通过从它拥有的其他配置生成一个简单的conf.py。但是，在本地进行更改时很难重现，尤其是对于我不拥有的项目。如果是这种情况，我找不到有关此功能的任何文档。如果我没有遗漏一些简单的东西（完全可能），有吗？

我的下一步将是编写一个新的 conf.py，并使其符合本地站点上的现有行为。如果我了解现有行为，这会更容易。

有问题的实际项目是 Jython 书：

https://jython.readthedocs.io/en/latest/ https://github.com/jython/book

没有运气在 google、stackoverflow、readthedocs doco 或问题上找到相关问题或问题。 https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/projects/models.py 的 readthedocs 代码似乎也检查了 conf.py。

Answer 1

嗯，有趣的是，您没有 conf.py，但文档仍然在 Date: 2017-10-24T19:18:40.379930Z 上成功构建。我和你一样傻眼。

无论如何，您可以在project's build's raw log file 下找到 RTD 最终使用的conf.py。这可能会为您节省一些悲伤。请注意，这些版本大约有 1.5 年的历史，因此您需要固定版本才能尝试准确地复制它。

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