Close sphinx-doc#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 @@
               '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

@@ -323,9 +323,13 @@ in the future.
 
    .. versionadded:: 4.0
 
-.. data:: master_doc
+.. data:: root_doc
 
-   The value of :confval:`master_doc`, for usage with :func:`pathto`.
+   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 @@ def read(self) -> List[str]:
         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 @@ def write(self, build_docnames: Iterable[str], updated_docnames: Sequence[str],
             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,28 +222,28 @@ def check_refnodes(self, nodes: List[Dict[str, Any]]) -> None:
                 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:
                 item['refuri'] = master_dir + item['refuri']
         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 @@ def build_toc(self) -> None:
         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 @@ def build_navigation_doc(self) -> None:
 
         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 @@ def prepare_writing(self, docnames: Set[str]) -> None:
             '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 @@ def finish(self) -> None:
 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 @@ def get_outdated_docs(self) -> Union[str, List[str]]:  # type: ignore
     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 @@ def get_relative_uri(self, from_: str, to: str, typ: str = None) -> str:
 
     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 @@ def _get_local_toctree(self, docname: str, collapse: bool = True, **kwargs: Any)
         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 @@ def assemble_toc_secnumbers(self) -> Dict[str, Dict[str, Tuple[int, ...]]]:
                 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 @@ def assemble_toc_fignumbers(self) -> Dict[str, Dict[str, Dict[str, Tuple[int, ..
                 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 @@ def write(self, *ignored: Any) -> None:
             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 @@ def copy_support_files(self) -> None:
 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 @@ def __init__(self, templatedir: str) -> None:
         self.templatedir = templatedir or ''
         super().__init__()
 
+    def _has_custom_temlate(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'] = d['master']
     d['now'] = time.asctime()
     d['project_underline'] = column_width(d['project']) * '='
     d.setdefault('extensions', [])
@@ -362,7 +375,13 @@ def write_file(fpath: str, content: str, newline: str = None) -> None:
     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'