The default setting for master_doc is changed to 'index'

CHANGES

@@ -7,6 +7,9 @@ Dependencies
 Incompatible changes
 --------------------
 
+* The default setting for :confval:`master_doc` is changed to ``'index'`` which
+  has been longly used as default of sphinx-quickstart.
+
 Deprecated
 ----------
 

doc/usage/configuration.rst

@@ -149,7 +149,10 @@ General configuration
 .. confval:: master_doc
 
    The document name of the "master" document, that is, the document that
-   contains the root :rst:dir:`toctree` directive.  Default is ``'contents'``.
+   contains the root :rst:dir:`toctree` directive.  Default is ``'index'``.
+
+   .. versionchanged:: 2.0
+      The defualt is changed to ``'index'`` from ``'contents'``.
 
 .. confval:: exclude_patterns
 

sphinx/config.py

@@ -104,7 +104,7 @@ class Config(object):
         locale_dirs = (['locales'], 'env', []),
         figure_language_filename = (u'{root}.{language}{ext}', 'env', [str]),
 
-        master_doc = ('contents', 'env', []),
+        master_doc = ('index', 'env', []),
         source_suffix = ({'.rst': 'restructuredtext'}, 'env', Any),
         source_encoding = ('utf-8-sig', 'env', []),
         source_parsers = ({}, 'env', []),

sphinx/templates/quickstart/conf.py_t

@@ -62,9 +62,11 @@ templates_path = ['{{ dot }}templates']
 # source_suffix = ['.rst', '.md']
 source_suffix = '{{ suffix }}'
 
+{% if master_doc != 'index' -%}
 # The master toctree document.
 master_doc = '{{ master_str }}'
 
+{% endif -%}
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #

tests/roots/test-build-text/conf.py

@@ -1,3 +1,2 @@
-master_doc = 'contents'
 source_suffix = '.txt'
 exclude_patterns = ['_build']

tests/roots/test-circular/sub.rst

@@ -1,3 +1,3 @@
 .. toctree::
 
-   contents
+   index

tests/roots/test-intl/conf.py

@@ -4,7 +4,7 @@ project = 'Sphinx intl <Tests>'
 source_suffix = '.txt'
 keep_warnings = True
 templates_path = ['_templates']
-html_additional_pages = {'index': 'index.html'}
+html_additional_pages = {'contents': 'contents.html'}
 release = version = '2013.120'
 gettext_additional_targets = ['index']
 exclude_patterns = ['_build']

tests/roots/test-intl/index.txt

@@ -10,7 +10,7 @@ CONTENTS
    :numbered:
    :caption: Table of Contents
 
-   subdir/contents
+   subdir/index
    bom
    warnings
    footnote

tests/roots/test-intl/role_xref.po

@@ -19,8 +19,8 @@ msgstr ""
 msgid "i18n role xref"
 msgstr "I18N ROCK'N ROLE XREF"
 
-msgid "link to :term:`Some term`, :ref:`i18n-role-xref`, :doc:`contents`."
-msgstr "LINK TO :ref:`i18n-role-xref`, :doc:`contents`, :term:`SOME NEW TERM`."
+msgid "link to :term:`Some term`, :ref:`i18n-role-xref`, :doc:`index`."
+msgstr "LINK TO :ref:`i18n-role-xref`, :doc:`index`, :term:`SOME NEW TERM`."
 
 msgid "same type links"
 msgstr "SAME TYPE LINKS"
@@ -31,8 +31,8 @@ msgstr "LINK TO :term:`SOME OTHER NEW TERM` AND :term:`SOME NEW TERM`."
 msgid "link to :ref:`i18n-role-xref` and :ref:`same-type-links`."
 msgstr "LINK TO :ref:`same-type-links` AND :ref:`i18n-role-xref`."
 
-msgid "link to :doc:`contents` and :doc:`glossary_terms`."
-msgstr "LINK TO :doc:`glossary_terms` AND :doc:`contents`."
+msgid "link to :doc:`index` and :doc:`glossary_terms`."
+msgstr "LINK TO :doc:`glossary_terms` AND :doc:`index`."
 
 msgid "link to :option:`-m` and :option:`--module`."
 msgstr "LINK TO :option:`--module` AND :option:`-m`."

tests/roots/test-intl/role_xref.txt

@@ -5,7 +5,7 @@
 i18n role xref
 ==============
 
-link to :term:`Some term`, :ref:`i18n-role-xref`, :doc:`contents`.
+link to :term:`Some term`, :ref:`i18n-role-xref`, :doc:`index`.
 
 .. _same-type-links:
 
@@ -16,7 +16,7 @@ link to :term:`Some term` and :term:`Some other term`.
 
 link to :ref:`i18n-role-xref` and :ref:`same-type-links`.
 
-link to :doc:`contents` and :doc:`glossary_terms`.
+link to :doc:`index` and :doc:`glossary_terms`.
 
 link to :option:`-m` and :option:`--module`.
 

tests/roots/test-numbered-circular/sub.rst

@@ -1,3 +1,3 @@
 .. toctree::
 
-   contents
+   index

tests/roots/test-root/conf.py

@@ -18,7 +18,6 @@ jsmath_path = 'dummy.js'
 
 templates_path = ['_templates']
 
-master_doc = 'contents'
 source_suffix = ['.txt', '.add', '.foo']
 
 project = 'Sphinx <Tests>'
@@ -37,8 +36,7 @@ rst_epilog = '.. |subst| replace:: global substitution'
 
 html_sidebars = {'**': ['localtoc.html', 'relations.html', 'sourcelink.html',
                         'customsb.html', 'searchbox.html'],
-                 'contents': ['contentssb.html', 'localtoc.html',
-                              'globaltoc.html']}
+                 'index': ['contentssb.html', 'localtoc.html', 'globaltoc.html']}
 html_style = 'default.css'
 html_last_updated_fmt = '%b %d, %Y'
 html_context = {'hckey': 'hcval', 'hckey_co': 'wrong_hcval_co'}
@@ -49,19 +47,19 @@ applehelp_bundle_id = 'org.sphinx-doc.Sphinx.help'
 applehelp_disable_external_tools = True
 
 latex_documents = [
-    ('contents', 'SphinxTests.tex', 'Sphinx Tests Documentation',
+    ('index', 'SphinxTests.tex', 'Sphinx Tests Documentation',
      'Georg Brandl \\and someone else', 'manual'),
 ]
 
 latex_additional_files = ['svgimg.svg']
 
 texinfo_documents = [
-    ('contents', 'SphinxTests', 'Sphinx Tests',
+    ('index', 'SphinxTests', 'Sphinx Tests',
      'Georg Brandl \\and someone else', 'Sphinx Testing', 'Miscellaneous'),
 ]
 
 man_pages = [
-    ('contents', 'SphinxTests', 'Sphinx Tests Documentation',
+    ('index', 'SphinxTests', 'Sphinx Tests Documentation',
      'Georg Brandl and someone else', 1),
 ]
 

tests/test_build.py

@@ -51,7 +51,7 @@ def nonascii_srcdir(request, rootdir, sphinx_test_tempdir):
             =======================
             """))
 
-        master_doc = srcdir / 'contents.txt'
+        master_doc = srcdir / 'index.txt'
         master_doc.write_text(master_doc.text() + dedent(u"""
                               .. toctree::
 
@@ -93,10 +93,10 @@ def test_circular_toctree(app, status, warning):
     warnings = warning.getvalue()
     assert (
         'circular toctree references detected, ignoring: '
-        'sub <- contents <- sub') in warnings
+        'sub <- index <- sub') in warnings
     assert (
         'circular toctree references detected, ignoring: '
-        'contents <- sub <- contents') in warnings
+        'index <- sub <- index') in warnings
 
 
 @pytest.mark.sphinx(buildername='text', testroot='numbered-circular')
@@ -105,10 +105,10 @@ def test_numbered_circular_toctree(app, status, warning):
     warnings = warning.getvalue()
     assert (
         'circular toctree references detected, ignoring: '
-        'sub <- contents <- sub') in warnings
+        'sub <- index <- sub') in warnings
     assert (
         'circular toctree references detected, ignoring: '
-        'contents <- sub <- contents') in warnings
+        'index <- sub <- index') in warnings
 
 
 @pytest.mark.sphinx(buildername='dummy', testroot='images')

tests/test_build_html.py

@@ -249,7 +249,7 @@ def test_html_warnings(app, warning):
         # footnote reference
         (".//a[@class='footnote-reference']", r'\[1\]'),
         # created by reference lookup
-        (".//a[@href='contents.html#ref1']", ''),
+        (".//a[@href='index.html#ref1']", ''),
         # ``seealso`` directive
         (".//div/p[@class='first admonition-title']", 'See also'),
         # a ``hlist`` directive
@@ -348,7 +348,7 @@ def test_html_warnings(app, warning):
         (".//a[@class='reference internal'][@href='#cmdoption-git-commit-p']/code/span",
          '-p'),
     ],
-    'contents.html': [
+    'index.html': [
         (".//meta[@name='hc'][@content='hcval']", ''),
         (".//meta[@name='hc_co'][@content='hcval_co']", ''),
         (".//td[@class='label']", r'\[Ref1\]'),

tests/test_build_html5.py

@@ -156,7 +156,7 @@ def cached_etree_parse():
         # footnote reference
         (".//a[@class='footnote-reference brackets']", r'1'),
         # created by reference lookup
-        (".//a[@href='contents.html#ref1']", ''),
+        (".//a[@href='index.html#ref1']", ''),
         # ``seealso`` directive
         (".//div/p[@class='admonition-title']", 'See also'),
         # a ``hlist`` directive
@@ -248,7 +248,7 @@ def cached_etree_parse():
         (".//a[@class='reference internal'][@href='#cmdoption-git-commit-p']/code/span",
          '-p'),
     ],
-    'contents.html': [
+    'index.html': [
         (".//meta[@name='hc'][@content='hcval']", ''),
         (".//meta[@name='hc_co'][@content='hcval_co']", ''),
         (".//dt[@class='label']/span[@class='brackets']", r'Ref1'),

tests/test_build_text.py

@@ -116,8 +116,8 @@ def test_list_items_in_admonition(app, status, warning):
 @with_text_app()
 def test_secnums(app, status, warning):
     app.builder.build_all()
-    contents = (app.outdir / 'contents.txt').text(encoding='utf8')
-    lines = contents.splitlines()
+    index = (app.outdir / 'index.txt').text(encoding='utf8')
+    lines = index.splitlines()
     assert lines[0] == "* 1. Section A"
     assert lines[1] == ""
     assert lines[2] == "* 2. Section B"
@@ -142,8 +142,8 @@ def test_secnums(app, status, warning):
 
     app.config.text_secnumber_suffix = " "
     app.builder.build_all()
-    contents = (app.outdir / 'contents.txt').text(encoding='utf8')
-    lines = contents.splitlines()
+    index = (app.outdir / 'index.txt').text(encoding='utf8')
+    lines = index.splitlines()
     assert lines[0] == "* 1 Section A"
     assert lines[1] == ""
     assert lines[2] == "* 2 Section B"
@@ -168,8 +168,8 @@ def test_secnums(app, status, warning):
 
     app.config.text_add_secnumbers = False
     app.builder.build_all()
-    contents = (app.outdir / 'contents.txt').text(encoding='utf8')
-    lines = contents.splitlines()
+    index = (app.outdir / 'index.txt').text(encoding='utf8')
+    lines = index.splitlines()
     assert lines[0] == "* Section A"
     assert lines[1] == ""
     assert lines[2] == "* Section B"

tests/test_builder.py

@@ -22,7 +22,7 @@ def test_incremental_reading(app):
 
     # before second reading, add, modify and remove source files
     (app.srcdir / 'new.txt').write_text('New file\n========\n')
-    app.env.all_docs['contents'] = 0  # mark as modified
+    app.env.all_docs['index'] = 0  # mark as modified
     (app.srcdir / 'autodoc.txt').unlink()
 
     # second reading
@@ -31,7 +31,7 @@ def test_incremental_reading(app):
     # "includes" and "images" are in there because they contain references
     # to nonexisting downloadable or image files, which are given another
     # chance to exist
-    assert set(updated) == set(['contents', 'new', 'includes', 'images'])
+    assert set(updated) == set(['index', 'new', 'includes', 'images'])
     assert 'autodoc' not in app.env.all_docs
     assert 'autodoc' not in app.env.found_docs
 

tests/test_config.py

@@ -78,7 +78,7 @@ def test_extension_values():
     config = Config()
 
     # check standard settings
-    assert config.master_doc == 'contents'
+    assert config.master_doc == 'index'
 
     # can't override it by add_config_value()
     with pytest.raises(ExtensionError) as excinfo:

tests/test_correct_year.py

@@ -33,5 +33,5 @@ def expect_date(request, monkeypatch):
 @pytest.mark.sphinx('html', testroot='correct-year')
 def test_correct_year(expect_date, app):
     app.build()
-    content = (app.outdir / 'contents.html').text()
+    content = (app.outdir / 'index.html').text()
     assert expect_date in content

tests/test_docutilsconf.py

@@ -27,7 +27,7 @@ def test_html_with_default_docutilsconf(app, status, warning):
     with patch_docutils(app.confdir):
         app.builder.build(['contents'])
 
-    result = (app.outdir / 'contents.html').text(encoding='utf-8')
+    result = (app.outdir / 'index.html').text(encoding='utf-8')
 
     assert regex_count(r'<th class="field-name">', result) == 1
     assert regex_count(r'<th class="field-name" colspan="2">', result) == 1
@@ -45,7 +45,7 @@ def test_html_with_docutilsconf(app, status, warning):
     with patch_docutils(app.confdir):
         app.builder.build(['contents'])
 
-    result = (app.outdir / 'contents.html').text(encoding='utf-8')
+    result = (app.outdir / 'index.html').text(encoding='utf-8')
 
     assert regex_count(r'<th class="field-name">', result) == 0
     assert regex_count(r'<th class="field-name" colspan="2">', result) == 2

tests/test_ext_autodoc.py

@@ -20,7 +20,7 @@ from sphinx import addnodes
 def test_autodoc(app, status, warning):
     app.builder.build_all()
 
-    content = pickle.loads((app.doctreedir / 'contents.doctree').bytes())
+    content = pickle.loads((app.doctreedir / 'index.doctree').bytes())
     assert isinstance(content[3], addnodes.desc)
     assert content[3][0].astext() == 'autodoc_dummy_module.test'
     assert content[3][1].astext() == 'Dummy function using dummy.*'

tests/test_intl.py

@@ -120,7 +120,7 @@ def assert_count(expected_expr, result, count):
 @pytest.mark.test_params(shared_result='test_intl_basic')
 def test_text_toctree(app):
     app.build()
-    result = (app.outdir / 'contents.txt').text(encoding='utf-8')
+    result = (app.outdir / 'index.txt').text(encoding='utf-8')
     assert_startswith(result, u"CONTENTS\n********\n\nTABLE OF CONTENTS\n")
 
 
@@ -169,7 +169,7 @@ def test_text_title_underline(app):
 def test_text_subdirs(app):
     app.build()
     # --- check translation in subdirs
-    result = (app.outdir / 'subdir' / 'contents.txt').text(encoding='utf-8')
+    result = (app.outdir / 'subdir' / 'index.txt').text(encoding='utf-8')
     assert_startswith(result, u"1. subdir contents\n******************\n")
 
 
@@ -462,8 +462,8 @@ def test_text_admonitions(app):
 def test_gettext_toctree(app):
     app.build()
     # --- toctree
-    expect = read_po(app.srcdir / 'contents.po')
-    actual = read_po(app.outdir / 'contents.pot')
+    expect = read_po(app.srcdir / 'index.po')
+    actual = read_po(app.outdir / 'index.pot')
     for expect_msg in [m for m in expect if m.id]:
         assert expect_msg.id in [m.id for m in actual if m.id]
 
@@ -629,7 +629,7 @@ def test_gettext_dont_rebuild_mo(make_app, app_params, build_mo):
 def test_html_meta(app):
     app.build()
     # --- test for meta
-    result = (app.outdir / 'contents.html').text(encoding='utf-8')
+    result = (app.outdir / 'index.html').text(encoding='utf-8')
     expected_expr = '<meta content="TESTDATA FOR I18N" name="description" />'
     assert expected_expr in result
     expected_expr = '<meta content="I18N, SPHINX, MARKUP" name="keywords" />'
@@ -758,7 +758,7 @@ def test_html_docfields(app):
 def test_html_template(app):
     app.build()
     # --- gettext template
-    result = (app.outdir / 'index.html').text(encoding='utf-8')
+    result = (app.outdir / 'contents.html').text(encoding='utf-8')
     assert "WELCOME" in result
     assert "SPHINX 2013.120" in result
 
@@ -941,7 +941,7 @@ def test_xml_role_xref(app):
         para1,
         ['LINK TO', "I18N ROCK'N ROLE XREF", ',', 'CONTENTS', ',',
          'SOME NEW TERM', '.'],
-        ['i18n-role-xref', 'contents',
+        ['i18n-role-xref', 'index',
          'glossary_terms#term-some-term'])
 
     para2 = sec2.findall('paragraph')
@@ -958,7 +958,7 @@ def test_xml_role_xref(app):
     assert_elem(
         para2[2],
         ['LINK TO', 'I18N WITH GLOSSARY TERMS', 'AND', 'CONTENTS', '.'],
-        ['glossary_terms', 'contents'])
+        ['glossary_terms', 'index'])
     assert_elem(
         para2[3],
         ['LINK TO', '--module', 'AND', '-m', '.'],

tests/test_setup_command.py

@@ -94,7 +94,7 @@ def nonascii_srcdir(request, setup_command):
         ==========================
         """))
 
-    master_doc = srcdir / 'contents.txt'
+    master_doc = srcdir / 'index.txt'
     master_doc.write_bytes((master_doc.text() + dedent("""
                             .. toctree::
 

tests/test_templating.py

@@ -21,7 +21,7 @@ def test_layout_overloading(make_app, app_params):
     setup_documenters(app)
     app.builder.build_update()
 
-    result = (app.outdir / 'contents.html').text(encoding='utf-8')
+    result = (app.outdir / 'index.html').text(encoding='utf-8')
 
     assert '<!-- layout overloading -->' in result
 

tests/test_util_images.py

@@ -19,7 +19,7 @@ from sphinx.util.images import (
 GIF_FILENAME = 'img.gif'
 PNG_FILENAME = 'img.png'
 PDF_FILENAME = 'img.pdf'
-TXT_FILENAME = 'contents.txt'
+TXT_FILENAME = 'index.txt'
 
 
 @pytest.fixture(scope='module')