Close #8326: Rename master_doc to root_doc

To describe the purpose more accurately, the `master_doc` is now renamed
to `root_doc`.  The old name is still available.  But it is recommeneded
to use new one from now on.

CHANGES

@@ -67,6 +67,7 @@ Features added
 * #8938: imgconverter: Show the error of the command availability check
 * #7830: Add debug logs for change detection of sources and templates
 * #8201: Emit a warning if toctree contains duplicated entries
+* #8326: ``master_doc`` is now renamed to :confval:`root_doc`
 
 Bugs fixed
 ----------

doc/_static/conf.py.txt

@@ -43,7 +43,7 @@ source_suffix = '.rst'
 # source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'index'
+root_doc = 'index'
 
 # General information about the project.
 project = u'test'
@@ -252,7 +252,7 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'test.tex', u'test Documentation',
+    (root_doc, 'test.tex', u'test Documentation',
      u'test', 'manual'),
 ]
 
@@ -283,7 +283,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'test', u'test Documentation',
+    (root_doc, 'test', u'test Documentation',
      [author], 1)
 ]
 
@@ -298,7 +298,7 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'test', u'test Documentation',
+    (root_doc, 'test', u'test Documentation',
      author, 'test', 'One line description of project.',
      'Miscellaneous'),
 ]

doc/conf.py

@@ -9,7 +9,7 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
               'sphinx.ext.intersphinx',
               'sphinx.ext.viewcode', 'sphinx.ext.inheritance_diagram']
 
-master_doc = 'contents'
+root_doc = 'contents'
 templates_path = ['_templates']
 exclude_patterns = ['_build']
 

doc/man/sphinx-apidoc.rst

@@ -145,7 +145,7 @@ These options are used when :option:`--full` is specified:
    * ``module.rst_t``
    * ``package.rst_t``
    * ``toc.rst_t``
-   * ``master_doc.rst_t``
+   * ``root_doc.rst_t``
    * ``conf.py_t``
    * ``Makefile_t``
    * ``Makefile.new_t``

doc/man/sphinx-quickstart.rst

@@ -72,7 +72,7 @@ Options
 
 .. option:: --master=MASTER
 
-   Master document name. (see :confval:`master_doc`).
+   Master document name. (see :confval:`root_doc`).
 
 .. rubric:: Extension Options
 
@@ -149,7 +149,7 @@ Options
    sphinx project files generated by quickstart.  Following Jinja2 template
    files are allowed:
 
-   * ``master_doc.rst_t``
+   * ``root_doc.rst_t``
    * ``conf.py_t``
    * ``Makefile_t``
    * ``Makefile.new_t``

doc/templating.rst

@@ -325,7 +325,19 @@ in the future.
 
 .. data:: master_doc
 
-   The value of :confval:`master_doc`, for usage with :func:`pathto`.
+   Same as :data:`root_doc`.
+
+   .. versionchanged:: 4.0
+
+      Renamed to ``root_doc``.
+
+.. data:: root_doc
+
+   The value of :confval:`root_doc`, for usage with :func:`pathto`.
+
+   .. versionchanged:: 4.0
+
+      Renamed from ``master_doc``.
 
 .. data:: pagename
 

doc/usage/configuration.rst

@@ -183,11 +183,20 @@ General configuration
 
 .. confval:: master_doc
 
-   The document name of the "master" document, that is, the document that
+   Same as :confval:`root_doc`.
+
+   .. versionchanged:: 4.0
+      Renamed ``master_doc`` to ``master_doc``.
+
+.. confval:: root_doc
+
+   The document name of the "root" document, that is, the document that
    contains the root :rst:dir:`toctree` directive.  Default is ``'index'``.
 
    .. versionchanged:: 2.0
       The default is changed to ``'index'`` from ``'contents'``.
+   .. versionchanged:: 4.0
+      Renamed ``master_doc`` from ``master_doc``.
 
 .. confval:: exclude_patterns
 
@@ -2023,8 +2032,8 @@ These options influence LaTeX output.
    *startdocname*
      String that specifies the :term:`document name` of the LaTeX file's master
      document.  All documents referenced by the *startdoc* document in TOC trees
-     will be included in the LaTeX file.  (If you want to use the default master
-     document for your LaTeX build, provide your :confval:`master_doc` here.)
+     will be included in the LaTeX file.  (If you want to use the default root
+     document for your LaTeX build, provide your :confval:`root_doc` here.)
 
    *targetname*
      File name of the LaTeX file in the output directory.
@@ -2293,7 +2302,7 @@ These options influence manual page output.
      String that specifies the :term:`document name` of the manual page's master
      document. All documents referenced by the *startdoc* document in TOC trees
      will be included in the manual file.  (If you want to use the default
-     master document for your manual pages build, use your :confval:`master_doc`
+     root document for your manual pages build, use your :confval:`root_doc`
      here.)
 
    *name*
@@ -2349,7 +2358,7 @@ These options influence Texinfo output.
      master document.  All documents referenced by the *startdoc* document in
      TOC trees will be included in the Texinfo file.  (If you want to use the
      default master document for your Texinfo build, provide your
-     :confval:`master_doc` here.)
+     :confval:`root_doc` here.)
 
    *targetname*
      File name (no extension) of the Texinfo file in the output directory.

doc/usage/restructuredtext/directives.rst

@@ -197,9 +197,9 @@ tables of contents.  The ``toctree`` directive is the central element.
    <metadata>` to let a document be built, but notify Sphinx that it is not
    reachable via a toctree.
 
-   The "master document" (selected by :confval:`master_doc`) is the "root" of
-   the TOC tree hierarchy.  It can be used as the documentation's main page, or
-   as a "full table of contents" if you don't give a ``maxdepth`` option.
+   The "root document" (selected by :confval:`root_doc`) is the "root" of the TOC
+   tree hierarchy.  It can be used as the documentation's main page, or as a
+   "full table of contents" if you don't give a ``maxdepth`` option.
 
    .. versionchanged:: 0.3
       Added "globbing" option.

sphinx/builders/__init__.py

@@ -413,9 +413,9 @@ class Builder:
         else:
             self._read_serial(docnames)
 
-        if self.config.master_doc not in self.env.all_docs:
-            raise SphinxError('master file %s not found' %
-                              self.env.doc2path(self.config.master_doc))
+        if self.config.root_doc not in self.env.all_docs:
+            raise SphinxError('root file %s not found' %
+                              self.env.doc2path(self.config.root_doc))
 
         for retval in self.events.emit('env-updated', self.env):
             if retval is not None:
@@ -517,7 +517,7 @@ class Builder:
             for tocdocname in self.env.files_to_rebuild.get(docname, set()):
                 if tocdocname in self.env.found_docs:
                     docnames.add(tocdocname)
-        docnames.add(self.config.master_doc)
+        docnames.add(self.config.root_doc)
 
         with progress_message(__('preparing documents')):
             self.prepare_writing(docnames)

sphinx/builders/_epub_base.py

@@ -222,14 +222,14 @@ class EpubBuilder(StandaloneHTMLBuilder):
                 appeared.add(node['refuri'])
 
     def get_toc(self) -> None:
-        """Get the total table of contents, containing the master_doc
+        """Get the total table of contents, containing the root_doc
         and pre and post files not managed by sphinx.
         """
-        doctree = self.env.get_and_resolve_doctree(self.config.master_doc,
+        doctree = self.env.get_and_resolve_doctree(self.config.root_doc,
                                                    self, prune_toctrees=False,
                                                    includehidden=True)
         self.refnodes = self.get_refnodes(doctree, [])
-        master_dir = path.dirname(self.config.master_doc)
+        master_dir = path.dirname(self.config.root_doc)
         if master_dir:
             master_dir += '/'  # XXX or os.sep?
             for item in self.refnodes:
@@ -237,13 +237,13 @@ class EpubBuilder(StandaloneHTMLBuilder):
         self.toc_add_files(self.refnodes)
 
     def toc_add_files(self, refnodes: List[Dict[str, Any]]) -> None:
-        """Add the master_doc, pre and post files to a list of refnodes.
+        """Add the root_doc, pre and post files to a list of refnodes.
         """
         refnodes.insert(0, {
             'level': 1,
-            'refuri': html.escape(self.config.master_doc + self.out_suffix),
+            'refuri': html.escape(self.config.root_doc + self.out_suffix),
             'text': ssp(html.escape(
-                self.env.titles[self.config.master_doc].astext()))
+                self.env.titles[self.config.root_doc].astext()))
         })
         for file, text in reversed(self.config.epub_pre_files):
             refnodes.insert(0, {
@@ -677,7 +677,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
         logger.info(__('writing toc.ncx file...'))
 
         if self.config.epub_tocscope == 'default':
-            doctree = self.env.get_and_resolve_doctree(self.config.master_doc,
+            doctree = self.env.get_and_resolve_doctree(self.config.root_doc,
                                                        self, prune_toctrees=False,
                                                        includehidden=False)
             refnodes = self.get_refnodes(doctree, [])

sphinx/builders/epub3.py

@@ -166,7 +166,7 @@ class Epub3Builder(_epub_base.EpubBuilder):
 
         if self.config.epub_tocscope == 'default':
             doctree = self.env.get_and_resolve_doctree(
-                self.config.master_doc, self,
+                self.config.root_doc, self,
                 prune_toctrees=False, includehidden=False)
             refnodes = self.get_refnodes(doctree, [])
             self.toc_add_files(refnodes)

sphinx/builders/html/__init__.py

@@ -494,7 +494,8 @@ class StandaloneHTMLBuilder(Builder):
             'version': self.config.version,
             'last_updated': self.last_updated,
             'copyright': self.config.copyright,
-            'master_doc': self.config.master_doc,
+            'master_doc': self.config.root_doc,
+            'root_doc': self.config.root_doc,
             'use_opensearch': self.config.html_use_opensearch,
             'docstitle': self.config.html_title,
             'shorttitle': self.config.html_short_title,

sphinx/builders/latex/__init__.py

@@ -517,7 +517,7 @@ def default_latex_documents(config: Config) -> List[Tuple[str, str, str, str, st
     """ Better default latex_documents settings. """
     project = texescape.escape(config.project, config.latex_engine)
     author = texescape.escape(config.author, config.latex_engine)
-    return [(config.master_doc,
+    return [(config.root_doc,
              make_filename_from_project(config.project) + '.tex',
              texescape.escape_abbr(project),
              texescape.escape_abbr(author),

sphinx/builders/manpage.py

@@ -109,7 +109,7 @@ class ManualPageBuilder(Builder):
 def default_man_pages(config: Config) -> List[Tuple[str, str, str, List[str], int]]:
     """ Better default man_pages settings. """
     filename = make_filename_from_project(config.project)
-    return [(config.master_doc, filename, '%s %s' % (config.project, config.release),
+    return [(config.root_doc, filename, '%s %s' % (config.project, config.release),
              [config.author], 1)]
 
 

sphinx/builders/singlehtml.py

@@ -42,7 +42,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
     def get_target_uri(self, docname: str, typ: str = None) -> str:
         if docname in self.env.all_docs:
             # all references are on the same page...
-            return self.config.master_doc + self.out_suffix + \
+            return self.config.root_doc + self.out_suffix + \
                 '#document-' + docname
         else:
             # chances are this is a html_additional_page
@@ -54,7 +54,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
 
     def fix_refuris(self, tree: Node) -> None:
         # fix refuris with double anchor
-        fname = self.config.master_doc + self.out_suffix
+        fname = self.config.root_doc + self.out_suffix
         for refnode in tree.traverse(nodes.reference):
             if 'refuri' not in refnode:
                 continue
@@ -75,7 +75,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
         return self.render_partial(toctree)['fragment']
 
     def assemble_doctree(self) -> nodes.document:
-        master = self.config.master_doc
+        master = self.config.root_doc
         tree = self.env.get_doctree(master)
         tree = inline_all_toctrees(self, set(), master, tree, darkgreen, [master])
         tree['docname'] = master
@@ -99,7 +99,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
                 alias = "%s/%s" % (docname, id)
                 new_secnumbers[alias] = secnum
 
-        return {self.config.master_doc: new_secnumbers}
+        return {self.config.root_doc: new_secnumbers}
 
     def assemble_toc_fignumbers(self) -> Dict[str, Dict[str, Dict[str, Tuple[int, ...]]]]:
         # Assemble toc_fignumbers to resolve figure numbers on SingleHTML.
@@ -120,11 +120,11 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
                 for id, fignum in fignums.items():
                     new_fignumbers[alias][id] = fignum
 
-        return {self.config.master_doc: new_fignumbers}
+        return {self.config.root_doc: new_fignumbers}
 
     def get_doc_context(self, docname: str, body: str, metatags: str) -> Dict:
         # no relation links...
-        toctree = TocTree(self.env).get_toctree_for(self.config.master_doc, self, False)
+        toctree = TocTree(self.env).get_toctree_for(self.config.root_doc, self, False)
         # if there is no toctree, toc is None
         if toctree:
             self.fix_refuris(toctree)
@@ -160,8 +160,8 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
             self.env.toc_fignumbers = self.assemble_toc_fignumbers()
 
         with progress_message(__('writing')):
-            self.write_doc_serialized(self.config.master_doc, doctree)
-            self.write_doc(self.config.master_doc, doctree)
+            self.write_doc_serialized(self.config.root_doc, doctree)
+            self.write_doc(self.config.root_doc, doctree)
 
     def finish(self) -> None:
         self.write_additional_files()

sphinx/builders/texinfo.py

@@ -197,7 +197,7 @@ class TexinfoBuilder(Builder):
 def default_texinfo_documents(config: Config) -> List[Tuple[str, str, str, str, str, str, str]]:  # NOQA
     """ Better default texinfo_documents settings. """
     filename = make_filename_from_project(config.project)
-    return [(config.master_doc, filename, config.project, config.author, filename,
+    return [(config.root_doc, filename, config.project, config.author, filename,
              'One line description of project', 'Miscellaneous')]
 
 

sphinx/cmd/quickstart.py

@@ -162,10 +162,22 @@ class QuickstartRenderer(SphinxRenderer):
         self.templatedir = templatedir or ''
         super().__init__()
 
+    def _has_custom_template(self, template_name: str) -> bool:
+        """Check if custom template file exists.
+
+        Note: Please don't use this function from extensions.
+              It will be removed in the future without deprecation period.
+        """
+        template = path.join(self.templatedir, path.basename(template_name))
+        if self.templatedir and path.exists(template):
+            return True
+        else:
+            return False
+
     def render(self, template_name: str, context: Dict) -> str:
-        user_template = path.join(self.templatedir, path.basename(template_name))
-        if self.templatedir and path.exists(user_template):
-            return self.render_from_file(user_template, context)
+        if self._has_custom_template(template_name):
+            custom_template = path.join(self.templatedir, path.basename(template_name))
+            return self.render_from_file(custom_template, context)
         else:
             return super().render(template_name, context)
 
@@ -318,6 +330,7 @@ def generate(d: Dict, overwrite: bool = True, silent: bool = False, templatedir:
     if 'mastertocmaxdepth' not in d:
         d['mastertocmaxdepth'] = 2
 
+    d['root_doc'] = d['master']
     d['now'] = time.asctime()
     d['project_underline'] = column_width(d['project']) * '='
     d.setdefault('extensions', [])
@@ -362,7 +375,13 @@ def generate(d: Dict, overwrite: bool = True, silent: bool = False, templatedir:
     write_file(path.join(srcdir, 'conf.py'), template.render_string(conf_text, d))
 
     masterfile = path.join(srcdir, d['master'] + d['suffix'])
-    write_file(masterfile, template.render('quickstart/master_doc.rst_t', d))
+    if template._has_custom_template('quickstart/master_doc.rst_t'):
+        msg = ('A custom template `master_doc.rst_t` found. It has been renamed to '
+               '`root_doc.rst_t`.  Please rename it on your project too.')
+        print(colorize('red', msg))  # RemovedInSphinx60Warning
+        write_file(masterfile, template.render('quickstart/master_doc.rst_t', d))
+    else:
+        write_file(masterfile, template.render('quickstart/root_doc.rst_t', d))
 
     if d.get('make_mode') is True:
         makefile_template = 'quickstart/Makefile.new_t'

sphinx/config.py

@@ -105,6 +105,7 @@ class Config:
         'figure_language_filename': ('{root}.{language}{ext}', 'env', [str]),
 
         'master_doc': ('index', 'env', []),
+        'root_doc': (lambda config: config.master_doc, 'env', []),
         'source_suffix': ({'.rst': 'restructuredtext'}, 'env', Any),
         'source_encoding': ('utf-8-sig', 'env', []),
         'exclude_patterns': ([], 'env', []),
@@ -461,17 +462,17 @@ def check_primary_domain(app: "Sphinx", config: Config) -> None:
         config.primary_domain = None  # type: ignore
 
 
-def check_master_doc(app: "Sphinx", env: "BuildEnvironment", added: Set[str],
-                     changed: Set[str], removed: Set[str]) -> Set[str]:
-    """Adjust master_doc to 'contents' to support an old project which does not have
-    no master_doc setting.
+def check_root_doc(app: "Sphinx", env: "BuildEnvironment", added: Set[str],
+                   changed: Set[str], removed: Set[str]) -> Set[str]:
+    """Adjust root_doc to 'contents' to support an old project which does not have
+    no root_doc setting.
     """
-    if (app.config.master_doc == 'index' and
+    if (app.config.root_doc == 'index' and
             'index' not in app.project.docnames and
             'contents' in app.project.docnames):
-        logger.warning(__('Since v2.0, Sphinx uses "index" as master_doc by default. '
-                          'Please add "master_doc = \'contents\'" to your conf.py.'))
-        app.config.master_doc = "contents"  # type: ignore
+        logger.warning(__('Since v2.0, Sphinx uses "index" as root_doc by default. '
+                          'Please add "root_doc = \'contents\'" to your conf.py.'))
+        app.config.root_doc = "contents"  # type: ignore
 
     return changed
 
@@ -483,7 +484,7 @@ def setup(app: "Sphinx") -> Dict[str, Any]:
     app.connect('config-inited', correct_copyright_year, priority=800)
     app.connect('config-inited', check_confval_types, priority=800)
     app.connect('config-inited', check_primary_domain, priority=800)
-    app.connect('env-get-outdated', check_master_doc)
+    app.connect('env-get-outdated', check_root_doc)
 
     return {
         'version': 'builtin',

sphinx/environment/__init__.py

@@ -600,7 +600,7 @@ class BuildEnvironment:
                         traversed.add(subdocname)
 
         relations = {}
-        docnames = traverse_toctree(None, self.config.master_doc)
+        docnames = traverse_toctree(None, self.config.root_doc)
         prevdoc = None
         parent, docname = next(docnames)
         for nextparent, nextdoc in docnames:
@@ -618,7 +618,7 @@ class BuildEnvironment:
         included = set().union(*self.included.values())  # type: ignore
         for docname in sorted(self.all_docs):
             if docname not in self.files_to_rebuild:
-                if docname == self.config.master_doc:
+                if docname == self.config.root_doc:
                     # the master file is not included anywhere ;)
                     continue
                 if docname in included:

sphinx/environment/adapters/toctree.py

@@ -315,7 +315,7 @@ class TocTree:
     def get_toctree_for(self, docname: str, builder: "Builder", collapse: bool,
                         **kwargs: Any) -> Element:
         """Return the global TOC nodetree."""
-        doctree = self.env.get_doctree(self.env.config.master_doc)
+        doctree = self.env.get_doctree(self.env.config.root_doc)
         toctrees = []  # type: List[Element]
         if 'includehidden' not in kwargs:
             kwargs['includehidden'] = True

sphinx/environment/collectors/toctree.py

@@ -281,7 +281,7 @@ class TocTreeCollector(EnvironmentCollector):
                 _walk_doctree(docname, doctree, secnum)
 
         if env.config.numfig:
-            _walk_doc(env.config.master_doc, tuple())
+            _walk_doc(env.config.root_doc, tuple())
             for docname, fignums in env.toc_fignumbers.items():
                 if fignums != old_fignumbers.get(docname):
                     rewrite_needed.append(docname)

sphinx/setup_command.py

@@ -190,6 +190,6 @@ class BuildDoc(Command):
             if not self.link_index:
                 continue
 
-            src = app.config.master_doc + app.builder.out_suffix  # type: ignore
+            src = app.config.root_doc + app.builder.out_suffix  # type: ignore
             dst = app.builder.get_outfilename('index')  # type: ignore
             os.symlink(src, dst)

sphinx/templates/htmlhelp/project.hhc

@@ -18,7 +18,7 @@
     </OBJECT>
     <UL>
       <LI>
-        {{ sitemap(short_title, master_doc)|indent(8) }}
+        {{ sitemap(short_title, root_doc)|indent(8) }}
       </LI>
       {%- for indexname, indexcls, content, collapse in domain_indices %}
       <LI>

sphinx/templates/htmlhelp/project.hhp

@@ -4,7 +4,7 @@ Binary Index=No
 Compiled file={{ outname }}.chm
 Contents file={{ outname }}.hhc
 Default Window={{ outname }}
-Default topic={{ master_doc }}
+Default topic={{ root_doc }}
 Display compile progress=No
 Full text search stop list file={{ outname }}.stp
 Full-text search=Yes
@@ -13,7 +13,7 @@ Language={{ "%#x"|format(lcid) }}
 Title={{ title }}
 
 [WINDOWS]
-{{ outname }}="{{ title }}","{{ outname }}.hhc","{{ outname }}.hhk","{{ master_doc }}","{{ master_doc }}",,,,,0x63520,220,0x10384e,[0,0,1024,768],,,,,,,0
+{{ outname }}="{{ title }}","{{ outname }}.hhc","{{ outname }}.hhk","{{ root_doc }}","{{ root_doc }}",,,,,0x63520,220,0x10384e,[0,0,1024,768],,,,,,,0
 
 [FILES]
 {%- for filename in files %}

sphinx/templates/quickstart/conf.py_t

@@ -64,9 +64,9 @@ templates_path = ['{{ dot }}templates']
 source_suffix = {{ suffix | repr }}
 
 {% endif -%}
-{% if master != 'index' -%}
-# The master toctree document.
-master_doc = {{ master | repr }}
+{% if root_doc != 'index' -%}
+# The root document.
+root_doc = {{ root_doc | repr }}
 
 {% endif -%}
 {% if language -%}

sphinx/themes/agogo/layout.html

@@ -14,13 +14,13 @@
     <div class="header-wrapper" role="banner">
       <div class="header">
         {%- if logo_url %}
-          <p class="logo"><a href="{{ pathto(master_doc)|e }}">
+          <p class="logo"><a href="{{ pathto(root_doc)|e }}">
             <img class="logo" src="{{ logo_url|e }}" alt="Logo"/>
           </a></p>
         {%- endif %}
         {%- block headertitle %}
         <div class="headertitle"><a
-          href="{{ pathto(master_doc)|e }}">{{ shorttitle|e }}</a></div>
+          href="{{ pathto(root_doc)|e }}">{{ shorttitle|e }}</a></div>
         {%- endblock %}
         <div class="rel" role="navigation" aria-label="related navigation">
           {%- for rellink in rellinks|reverse %}

sphinx/themes/basic/globaltoc.html

@@ -7,5 +7,5 @@
     :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 #}
-<h3><a href="{{ pathto(master_doc)|e }}">{{ _('Table of Contents') }}</a></h3>
+<h3><a href="{{ pathto(root_doc)|e }}">{{ _('Table of Contents') }}</a></h3>
 {{ toctree(includehidden=theme_globaltoc_includehidden, collapse=theme_globaltoc_collapse, maxdepth=theme_globaltoc_maxdepth) }}

sphinx/themes/basic/layout.html

@@ -35,7 +35,7 @@
           {%- if not loop.first %}{{ reldelim2 }}{% endif %}</li>
         {%- endfor %}
         {%- block rootrellink %}
-        <li class="nav-item nav-item-0"><a href="{{ pathto(master_doc)|e }}">{{ shorttitle|e }}</a>{{ reldelim1 }}</li>
+        <li class="nav-item nav-item-0"><a href="{{ pathto(root_doc)|e }}">{{ shorttitle|e }}</a>{{ reldelim1 }}</li>
         {%- endblock %}
         {%- for parent in parents %}
           <li class="nav-item nav-item-{{ loop.index }}"><a href="{{ parent.link|e }}" {% if loop.last %}{{ accesskey("U") }}{% endif %}>{{ parent.title }}</a>{{ reldelim1 }}</li>
@@ -52,7 +52,7 @@
         <div class="sphinxsidebarwrapper">
           {%- block sidebarlogo %}
           {%- if logo_url %}
-            <p class="logo"><a href="{{ pathto(master_doc)|e }}">
+            <p class="logo"><a href="{{ pathto(root_doc)|e }}">
               <img class="logo" src="{{ logo_url|e }}" alt="Logo"/>
             </a></p>
           {%- endif %}

sphinx/themes/basic/localtoc.html

@@ -8,6 +8,6 @@
     :license: BSD, see LICENSE for details.
 #}
 {%- if display_toc %}
-  <h3><a href="{{ pathto(master_doc)|e }}">{{ _('Table of Contents') }}</a></h3>
+  <h3><a href="{{ pathto(root_doc)|e }}">{{ _('Table of Contents') }}</a></h3>
   {{ toc }}
 {%- endif %}

sphinx/themes/haiku/layout.html

@@ -21,7 +21,7 @@
         «&#160;&#160;<a href="{{ prev.link|e }}">{{ prev.title }}</a>
         &#160;&#160;::&#160;&#160;
         {%- endif %}
-        <a class="uplink" href="{{ pathto(master_doc)|e }}">{{ _('Contents') }}</a>
+        <a class="uplink" href="{{ pathto(root_doc)|e }}">{{ _('Contents') }}</a>
         {%- if next %}
         &#160;&#160;::&#160;&#160;
         <a href="{{ next.link|e }}">{{ next.title }}</a>&#160;&#160;»

sphinx/themes/pyramid/layout.html

@@ -12,7 +12,7 @@
 {%- if logo %}
 <div class="header" role="banner">
   <div class="logo">
-    <a href="{{ pathto(master_doc)|e }}">
+    <a href="{{ pathto(root_doc)|e }}">
       <img class="logo" src="{{ pathto(logo, 1)|e }}" alt="Logo"/>
     </a>
   </div>

tests/roots/test-ext-doctest-skipif/conf.py

@@ -1,7 +1,7 @@
 extensions = ['sphinx.ext.doctest']
 
 project = 'test project for the doctest :skipif: directive'
-master_doc = 'skipif'
+root_doc = 'skipif'
 source_suffix = '.txt'
 exclude_patterns = ['_build']
 

tests/roots/test-ext-doctest/conf.py

@@ -1,6 +1,6 @@
 extensions = ['sphinx.ext.doctest']
 
 project = 'test project for doctest'
-master_doc = 'doctest'
+root_doc = 'doctest'
 source_suffix = '.txt'
 exclude_patterns = ['_build']

tests/roots/test-latex-equations/conf.py

@@ -1,2 +1,2 @@
-master_doc = 'equations'
+root_doc = 'equations'
 extensions = ['sphinx.ext.imgmath']

tests/roots/test-latex-includegraphics/conf.py

@@ -1,5 +1,3 @@
-master_doc = 'index'
-
 exclude_patterns = ['_build']
 
 latex_elements = {

tests/roots/test-linkcheck/conf.py

@@ -1,4 +1,4 @@
-master_doc = 'links'
+root_doc = 'links'
 source_suffix = '.txt'
 exclude_patterns = ['_build']
 linkcheck_anchors = True

tests/test_build.py

@@ -48,12 +48,12 @@ def nonascii_srcdir(request, rootdir, sphinx_test_tempdir):
             =======================
             """))
 
-        master_doc = srcdir / 'index.txt'
-        master_doc.write_text(master_doc.read_text() + dedent("""
-                              .. toctree::
+        root_doc = srcdir / 'index.txt'
+        root_doc.write_text(root_doc.read_text() + dedent("""
+                            .. toctree::
 
-                                 %(test_name)s/%(test_name)s
-                              """ % {'test_name': test_name}))
+                               %(test_name)s/%(test_name)s
+                            """ % {'test_name': test_name}))
     return srcdir
 
 
@@ -71,7 +71,7 @@ def test_build_all(requests_head, make_app, nonascii_srcdir, buildername):
     app.build()
 
 
-def test_master_doc_not_found(tempdir, make_app):
+def test_root_doc_not_found(tempdir, make_app):
     (tempdir / 'conf.py').write_text('')
     assert tempdir.listdir() == ['conf.py']
 

tests/test_build_latex.py

@@ -1037,7 +1037,7 @@ def test_toctree_maxdepth_howto(app, status, warning):
 
 @pytest.mark.sphinx(
     'latex', testroot='toctree-maxdepth',
-    confoverrides={'master_doc': 'foo'})
+    confoverrides={'root_doc': 'foo'})
 def test_toctree_not_found(app, status, warning):
     app.builder.build_all()
     result = (app.outdir / 'python.tex').read_text()
@@ -1051,7 +1051,7 @@ def test_toctree_not_found(app, status, warning):
 
 @pytest.mark.sphinx(
     'latex', testroot='toctree-maxdepth',
-    confoverrides={'master_doc': 'bar'})
+    confoverrides={'root_doc': 'bar'})
 def test_toctree_without_maxdepth(app, status, warning):
     app.builder.build_all()
     result = (app.outdir / 'python.tex').read_text()
@@ -1064,7 +1064,7 @@ def test_toctree_without_maxdepth(app, status, warning):
 
 @pytest.mark.sphinx(
     'latex', testroot='toctree-maxdepth',
-    confoverrides={'master_doc': 'qux'})
+    confoverrides={'root_doc': 'qux'})
 def test_toctree_with_deeper_maxdepth(app, status, warning):
     app.builder.build_all()
     result = (app.outdir / 'python.tex').read_text()
@@ -1532,7 +1532,7 @@ def test_latex_figure_in_admonition(app, status, warning):
 def test_default_latex_documents():
     from sphinx.util import texescape
     texescape.init()
-    config = Config({'master_doc': 'index',
+    config = Config({'root_doc': 'index',
                      'project': 'STASI™ Documentation',
                      'author': "Wolfgang Schäuble & G'Beckstein."})
     config.init_values()

tests/test_config.py

@@ -20,7 +20,7 @@ from sphinx.testing.path import path
 
 
 @pytest.mark.sphinx(testroot='config', confoverrides={
-    'master_doc': 'master',
+    'root_doc': 'root',
     'nonexisting_value': 'True',
     'latex_elements.maketitle': 'blah blah blah',
     'modindex_common_prefix': 'path1,path2'})
@@ -33,7 +33,7 @@ def test_core_config(app, status, warning):
     assert cfg.templates_path == ['_templates']
 
     # overrides
-    assert cfg.master_doc == 'master'
+    assert cfg.root_doc == 'root'
     assert cfg.latex_elements['maketitle'] == 'blah blah blah'
     assert cfg.modindex_common_prefix == ['path1', 'path2']
 
@@ -78,11 +78,11 @@ def test_extension_values():
     config = Config()
 
     # check standard settings
-    assert config.master_doc == 'index'
+    assert config.root_doc == 'index'
 
     # can't override it by add_config_value()
     with pytest.raises(ExtensionError) as excinfo:
-        config.add('master_doc', 'index', 'env', None)
+        config.add('root_doc', 'index', 'env', None)
     assert 'already present' in str(excinfo.value)
 
     # add a new config value
@@ -201,13 +201,13 @@ def test_config_eol(logger, tempdir):
         assert logger.called is False
 
 
-@pytest.mark.sphinx(confoverrides={'master_doc': 123,
+@pytest.mark.sphinx(confoverrides={'root_doc': 123,
                                    'language': 'foo',
                                    'primary_domain': None})
 def test_builtin_conf(app, status, warning):
     warnings = warning.getvalue()
-    assert 'master_doc' in warnings, (
-        'override on builtin "master_doc" should raise a type warning')
+    assert 'root_doc' in warnings, (
+        'override on builtin "root_doc" should raise a type warning')
     assert 'language' not in warnings, (
         'explicitly permitted override on builtin "language" should NOT raise '
         'a type warning')

tests/test_environment.py

@@ -35,14 +35,14 @@ def test_config_status(make_app, app_params):
     assert "0 added, 0 changed, 0 removed" in app2._status.getvalue()
 
     # incremental build (config entry changed)
-    app3 = make_app(*args, confoverrides={'master_doc': 'indexx'}, **kwargs)
+    app3 = make_app(*args, confoverrides={'root_doc': 'indexx'}, **kwargs)
     fname = os.path.join(app3.srcdir, 'index.rst')
     assert os.path.isfile(fname)
     shutil.move(fname, fname[:-4] + 'x.rst')
     assert app3.env.config_status == CONFIG_CHANGED
     app3.build()
     shutil.move(fname[:-4] + 'x.rst', fname)
-    assert "[config changed ('master_doc')] 1 added" in app3._status.getvalue()
+    assert "[config changed ('root_doc')] 1 added" in app3._status.getvalue()
 
     # incremental build (extension changed)
     app4 = make_app(*args, confoverrides={'extensions': ['sphinx.ext.autodoc']}, **kwargs)

tests/test_quickstart.py

@@ -163,7 +163,7 @@ def test_quickstart_all_answers(tempdir):
     ]
     assert ns['templates_path'] == ['.templates']
     assert ns['source_suffix'] == '.txt'
-    assert ns['master_doc'] == 'contents'
+    assert ns['root_doc'] == 'contents'
     assert ns['project'] == 'STASI™'
     assert ns['copyright'] == '%s, Wolfgang Schäuble & G\'Beckstein' % \
         time.strftime('%Y')

tests/test_setup_command.py

@@ -93,12 +93,12 @@ def nonascii_srcdir(request, setup_command):
         ==========================
         """))
 
-    master_doc = srcdir / 'index.txt'
-    master_doc.write_bytes((master_doc.read_text() + dedent("""
-                            .. toctree::
+    root_doc = srcdir / 'index.txt'
+    root_doc.write_bytes((root_doc.read_text() + dedent("""
+                          .. toctree::
 
-                               %(mb_name)s/%(mb_name)s
-                            """ % locals())).encode())
+                             %(mb_name)s/%(mb_name)s
+                          """ % locals())).encode())
 
 
 @pytest.mark.usefixtures('nonascii_srcdir')