diff --git a/CHANGES b/CHANGES index 8eb23b97a..7b3291b56 100644 --- a/CHANGES +++ b/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 ---------- diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index b733e13e1..2931c0329 100644 --- a/doc/usage/configuration.rst +++ b/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 diff --git a/sphinx/config.py b/sphinx/config.py index ec54f1691..b4b734d13 100644 --- a/sphinx/config.py +++ b/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', []), diff --git a/sphinx/templates/quickstart/conf.py_t b/sphinx/templates/quickstart/conf.py_t index 79c78ae93..0be8c3f2c 100644 --- a/sphinx/templates/quickstart/conf.py_t +++ b/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. # diff --git a/tests/roots/test-autosummary/contents.rst b/tests/roots/test-autosummary/index.rst similarity index 100% rename from tests/roots/test-autosummary/contents.rst rename to tests/roots/test-autosummary/index.rst diff --git a/tests/roots/test-build-text/conf.py b/tests/roots/test-build-text/conf.py index 23d0ae840..fd9eefbf6 100644 --- a/tests/roots/test-build-text/conf.py +++ b/tests/roots/test-build-text/conf.py @@ -1,3 +1,2 @@ -master_doc = 'contents' source_suffix = '.txt' exclude_patterns = ['_build'] diff --git a/tests/roots/test-build-text/contents.txt b/tests/roots/test-build-text/index.txt similarity index 100% rename from tests/roots/test-build-text/contents.txt rename to tests/roots/test-build-text/index.txt diff --git a/tests/roots/test-circular/contents.rst b/tests/roots/test-circular/index.rst similarity index 100% rename from tests/roots/test-circular/contents.rst rename to tests/roots/test-circular/index.rst diff --git a/tests/roots/test-circular/sub.rst b/tests/roots/test-circular/sub.rst index 070c39743..cebfd6587 100644 --- a/tests/roots/test-circular/sub.rst +++ b/tests/roots/test-circular/sub.rst @@ -1,3 +1,3 @@ .. toctree:: - contents + index diff --git a/tests/roots/test-correct-year/contents.rst b/tests/roots/test-correct-year/index.rst similarity index 100% rename from tests/roots/test-correct-year/contents.rst rename to tests/roots/test-correct-year/index.rst diff --git a/tests/roots/test-directive-only/contents.rst b/tests/roots/test-directive-only/index.rst similarity index 100% rename from tests/roots/test-directive-only/contents.rst rename to tests/roots/test-directive-only/index.rst diff --git a/tests/roots/test-docutilsconf/contents.txt b/tests/roots/test-docutilsconf/index.txt similarity index 100% rename from tests/roots/test-docutilsconf/contents.txt rename to tests/roots/test-docutilsconf/index.txt diff --git a/tests/roots/test-ext-autodoc/contents.rst b/tests/roots/test-ext-autodoc/index.rst similarity index 100% rename from tests/roots/test-ext-autodoc/contents.rst rename to tests/roots/test-ext-autodoc/index.rst diff --git a/tests/roots/test-ext-autosummary/contents.rst b/tests/roots/test-ext-autosummary/index.rst similarity index 100% rename from tests/roots/test-ext-autosummary/contents.rst rename to tests/roots/test-ext-autosummary/index.rst diff --git a/tests/roots/test-gettext-template/contents.rst b/tests/roots/test-gettext-template/index.rst similarity index 100% rename from tests/roots/test-gettext-template/contents.rst rename to tests/roots/test-gettext-template/index.rst diff --git a/tests/roots/test-inheritance/contents.rst b/tests/roots/test-inheritance/index.rst similarity index 100% rename from tests/roots/test-inheritance/contents.rst rename to tests/roots/test-inheritance/index.rst diff --git a/tests/roots/test-intl/_templates/index.html b/tests/roots/test-intl/_templates/contents.html similarity index 100% rename from tests/roots/test-intl/_templates/index.html rename to tests/roots/test-intl/_templates/contents.html diff --git a/tests/roots/test-intl/conf.py b/tests/roots/test-intl/conf.py index aafd9ba79..0306ff38e 100644 --- a/tests/roots/test-intl/conf.py +++ b/tests/roots/test-intl/conf.py @@ -4,7 +4,7 @@ project = 'Sphinx intl ' 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'] diff --git a/tests/roots/test-intl/contents.po b/tests/roots/test-intl/index.po similarity index 100% rename from tests/roots/test-intl/contents.po rename to tests/roots/test-intl/index.po diff --git a/tests/roots/test-intl/contents.txt b/tests/roots/test-intl/index.txt similarity index 95% rename from tests/roots/test-intl/contents.txt rename to tests/roots/test-intl/index.txt index b818e99c7..cd63b5ec3 100644 --- a/tests/roots/test-intl/contents.txt +++ b/tests/roots/test-intl/index.txt @@ -10,7 +10,7 @@ CONTENTS :numbered: :caption: Table of Contents - subdir/contents + subdir/index bom warnings footnote diff --git a/tests/roots/test-intl/role_xref.po b/tests/roots/test-intl/role_xref.po index 5b6d114c0..81ee22c6e 100644 --- a/tests/roots/test-intl/role_xref.po +++ b/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`." diff --git a/tests/roots/test-intl/role_xref.txt b/tests/roots/test-intl/role_xref.txt index b3d42d127..875af4667 100644 --- a/tests/roots/test-intl/role_xref.txt +++ b/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`. diff --git a/tests/roots/test-intl/subdir/contents.txt b/tests/roots/test-intl/subdir/index.txt similarity index 100% rename from tests/roots/test-intl/subdir/contents.txt rename to tests/roots/test-intl/subdir/index.txt diff --git a/tests/roots/test-numbered-circular/contents.rst b/tests/roots/test-numbered-circular/index.rst similarity index 100% rename from tests/roots/test-numbered-circular/contents.rst rename to tests/roots/test-numbered-circular/index.rst diff --git a/tests/roots/test-numbered-circular/sub.rst b/tests/roots/test-numbered-circular/sub.rst index 070c39743..cebfd6587 100644 --- a/tests/roots/test-numbered-circular/sub.rst +++ b/tests/roots/test-numbered-circular/sub.rst @@ -1,3 +1,3 @@ .. toctree:: - contents + index diff --git a/tests/roots/test-root/conf.py b/tests/roots/test-root/conf.py index d5029a776..42b8295a2 100644 --- a/tests/roots/test-root/conf.py +++ b/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 ' @@ -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), ] diff --git a/tests/roots/test-root/contents.txt b/tests/roots/test-root/index.txt similarity index 100% rename from tests/roots/test-root/contents.txt rename to tests/roots/test-root/index.txt diff --git a/tests/roots/test-setup/doc/contents.txt b/tests/roots/test-setup/doc/index.txt similarity index 100% rename from tests/roots/test-setup/doc/contents.txt rename to tests/roots/test-setup/doc/index.txt diff --git a/tests/roots/test-templating/contents.txt b/tests/roots/test-templating/index.txt similarity index 100% rename from tests/roots/test-templating/contents.txt rename to tests/roots/test-templating/index.txt diff --git a/tests/test_build.py b/tests/test_build.py index 47d76b2a2..193de4043 100644 --- a/tests/test_build.py +++ b/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') diff --git a/tests/test_build_html.py b/tests/test_build_html.py index b8286edb3..05d71cf12 100644 --- a/tests/test_build_html.py +++ b/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\]'), diff --git a/tests/test_build_html5.py b/tests/test_build_html5.py index 82050cee1..d839b9741 100644 --- a/tests/test_build_html5.py +++ b/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'), diff --git a/tests/test_build_text.py b/tests/test_build_text.py index f89187c85..b9e0e61a1 100644 --- a/tests/test_build_text.py +++ b/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" diff --git a/tests/test_builder.py b/tests/test_builder.py index d58091e8d..dbc9d3dae 100644 --- a/tests/test_builder.py +++ 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 diff --git a/tests/test_config.py b/tests/test_config.py index 5dd05550c..156b193fc 100644 --- a/tests/test_config.py +++ b/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: diff --git a/tests/test_correct_year.py b/tests/test_correct_year.py index e7501bb6a..8995cef5b 100644 --- a/tests/test_correct_year.py +++ b/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 diff --git a/tests/test_docutilsconf.py b/tests/test_docutilsconf.py index 989edc6a8..f6439fff4 100644 --- a/tests/test_docutilsconf.py +++ b/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'', result) == 1 assert regex_count(r'', 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'', result) == 0 assert regex_count(r'', result) == 2 diff --git a/tests/test_ext_autodoc.py b/tests/test_ext_autodoc.py index 44470771d..50716f8e6 100644 --- a/tests/test_ext_autodoc.py +++ b/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.*' diff --git a/tests/test_intl.py b/tests/test_intl.py index c8f90e41c..6b1c0236a 100644 --- a/tests/test_intl.py +++ b/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 = '' assert expected_expr in result expected_expr = '' @@ -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', '.'], diff --git a/tests/test_setup_command.py b/tests/test_setup_command.py index cd1f89c0c..51cfca205 100644 --- a/tests/test_setup_command.py +++ b/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:: diff --git a/tests/test_templating.py b/tests/test_templating.py index 8eed1fdf8..3ae560c9e 100644 --- a/tests/test_templating.py +++ b/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 '' in result diff --git a/tests/test_util_images.py b/tests/test_util_images.py index 624690831..5a98fa003 100644 --- a/tests/test_util_images.py +++ b/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')