Как readthedocs генерирует Sphinx HTML из RST без conf.py?

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-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 или проблемах.Код readthedocs на https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/projects/models.py, кажется, также проверяет на conf.py.

Answer 1

Да, интересно, что у вас нет conf.py, но документы все еще успешно созданы на Date: 2017-10-24T19:18:40.379930Z. Я так же ошеломлен, как и ты.

В любом случае, вы можете найти conf.py, который RTD заканчивает использовать в файле необработанного журнала проекта *1007*. Это может спасти вас немного горя. Обратите внимание, что версиям около 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"]