Merge pull request #5607 from tk0miya/smart_texinfo_conf_py

quickstart: Simplify generated conf.py (for texinfo)

doc/usage/configuration.rst

@@ -60,6 +60,36 @@ Important points to note:
   created *after* the builder is initialized.
 
 
+Project information
+-------------------
+
+.. confval:: project
+
+   The documented project's name.
+
+.. confval:: author
+
+   The author name(s) of the document.  The default value is ``'unknown'``.
+
+.. confval:: copyright
+
+   A copyright statement in the style ``'2008, Author Name'``.
+
+.. confval:: version
+
+   The major project version, used as the replacement for ``|version|``.  For
+   example, for the Python documentation, this may be something like ``2.6``.
+
+.. confval:: release
+
+   The full project version, used as the replacement for ``|release|`` and
+   e.g. in the HTML templates.  For example, for the Python documentation, this
+   may be something like ``2.6.0rc1``.
+
+   If you don't need the separation provided between :confval:`version` and
+   :confval:`release`, just set them both to the same value.
+
+
 General configuration
 ---------------------
 
@@ -480,36 +510,6 @@ General configuration
 
    .. versionadded:: 1.5
 
-
-Project information
--------------------
-
-.. confval:: project
-
-   The documented project's name.
-
-.. confval:: author
-
-   The author name(s) of the document.  The default value is ``'unknown'``.
-
-.. confval:: copyright
-
-   A copyright statement in the style ``'2008, Author Name'``.
-
-.. confval:: version
-
-   The major project version, used as the replacement for ``|version|``.  For
-   example, for the Python documentation, this may be something like ``2.6``.
-
-.. confval:: release
-
-   The full project version, used as the replacement for ``|release|`` and
-   e.g. in the HTML templates.  For example, for the Python documentation, this
-   may be something like ``2.6.0rc1``.
-
-   If you don't need the separation provided between :confval:`version` and
-   :confval:`release`, just set them both to the same value.
-
 .. confval:: today
              today_fmt
 

sphinx/builders/texinfo.py

@@ -28,12 +28,13 @@ from sphinx.util.console import bold, darkgreen  # type: ignore
 from sphinx.util.docutils import new_document
 from sphinx.util.fileutil import copy_asset_file
 from sphinx.util.nodes import inline_all_toctrees
-from sphinx.util.osutil import SEP, make_filename
+from sphinx.util.osutil import SEP, make_filename_from_project
 from sphinx.writers.texinfo import TexinfoWriter, TexinfoTranslator
 
 if False:
     # For type annotation
     from sphinx.application import Sphinx  # NOQA
+    from sphinx.config import Config  # NOQA
     from typing import Any, Dict, Iterable, List, Tuple, Union  # NOQA
     from sphinx.util.typing import unicode  # NOQA
 
@@ -210,17 +211,19 @@ class TexinfoBuilder(Builder):
                                    path.join(self.srcdir, src), err)
 
 
+def default_texinfo_documents(config):
+    # type: (Config) -> List[Tuple[unicode, unicode, unicode, unicode, unicode, unicode, unicode]]  # NOQA
+    """ Better default texinfo_documents settings. """
+    filename = make_filename_from_project(config.project)
+    return [(config.master_doc, filename, config.project, config.author, filename,
+             'One line description of project', 'Miscellaneous')]
+
+
 def setup(app):
     # type: (Sphinx) -> Dict[unicode, Any]
     app.add_builder(TexinfoBuilder)
 
-    app.add_config_value('texinfo_documents',
+    app.add_config_value('texinfo_documents', default_texinfo_documents, None)
-                         lambda self: [(self.master_doc, make_filename(self.project).lower(),
-                                        self.project, '', make_filename(self.project),
-                                        'The %s reference manual.' %
-                                        make_filename(self.project),
-                                        'Python')],
-                         None)
     app.add_config_value('texinfo_appendices', [], None)
     app.add_config_value('texinfo_elements', {}, None)
     app.add_config_value('texinfo_domain_indices', True, None, [list])

sphinx/templates/quickstart/conf.py_t

@@ -157,18 +157,6 @@ man_pages = [
 ]
 
 
-# -- Options for Texinfo output ----------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (master_doc, '{{ project_fn }}', u'{{ project_doc_str }}',
-     author, '{{ project_fn }}', 'One line description of project.',
-     'Miscellaneous'),
-]
-
-
 # -- Options for Epub output -------------------------------------------------
 
 # Bibliographic Dublin Core info.

sphinx/util/osutil.py

@@ -140,6 +140,7 @@ def copyfile(source, dest):
 
 
 no_fn_re = re.compile(r'[^a-zA-Z0-9_-]')
+project_suffix_re = re.compile(' Documentation$')
 
 
 def make_filename(string):
@@ -147,6 +148,11 @@ def make_filename(string):
     return no_fn_re.sub('', string) or 'sphinx'
 
 
+def make_filename_from_project(project):
+    # type: (str) -> unicode
+    return make_filename(project_suffix_re.sub('', project)).lower()
+
+
 def ustrftime(format, *args):
     # type: (unicode, Any) -> unicode
     """[DEPRECATED] strftime for unicode strings."""

tests/roots/test-root/conf.py

@@ -53,11 +53,6 @@ latex_documents = [
 
 latex_additional_files = ['svgimg.svg']
 
-texinfo_documents = [
-    ('index', 'SphinxTests', 'Sphinx Tests',
-     'Georg Brandl \\and someone else', 'Sphinx Testing', 'Miscellaneous'),
-]
-
 man_pages = [
     ('index', 'SphinxTests', 'Sphinx Tests Documentation',
      'Georg Brandl and someone else', 1),

tests/test_build_texinfo.py

@@ -17,6 +17,8 @@ from subprocess import Popen, PIPE
 import pytest
 from test_build_html import ENV_WARNINGS
 
+from sphinx.builders.texinfo import default_texinfo_documents
+from sphinx.config import Config
 from sphinx.testing.util import strip_escseq
 from sphinx.writers.texinfo import TexinfoTranslator
 
@@ -46,7 +48,7 @@ def test_texinfo_warnings(app, status, warning):
 def test_texinfo(app, status, warning):
     TexinfoTranslator.ignore_missing_images = True
     app.builder.build_all()
-    result = (app.outdir / 'SphinxTests.texi').text(encoding='utf8')
+    result = (app.outdir / 'sphinxtests.texi').text(encoding='utf8')
     assert ('@anchor{markup doc}@anchor{11}'
             '@anchor{markup id1}@anchor{12}'
             '@anchor{markup testing-various-markup}@anchor{13}' in result)
@@ -55,7 +57,7 @@ def test_texinfo(app, status, warning):
     os.chdir(app.outdir)
     try:
         try:
-            p = Popen(['makeinfo', '--no-split', 'SphinxTests.texi'],
+            p = Popen(['makeinfo', '--no-split', 'sphinxtests.texi'],
                       stdout=PIPE, stderr=PIPE)
         except OSError:
             raise pytest.skip.Exception  # most likely makeinfo was not found
@@ -89,3 +91,14 @@ def test_texinfo_citation(app, status, warning):
             'This is a citation\n') in output
     assert ('@anchor{index cite2}@anchor{2}@w{(CITE2)} \n'
             'This is a multiline citation\n') in output
+
+
+def test_default_texinfo_documents():
+    config = Config({'master_doc': 'index',
+                     'project': u'STASI™ Documentation',
+                     'author': u"Wolfgang Schäuble & G'Beckstein"})
+    config.init_values()
+    expected = [('index', 'stasi', u'STASI™ Documentation',
+                 u"Wolfgang Schäuble & G'Beckstein", 'stasi',
+                 'One line description of project', 'Miscellaneous')]
+    assert default_texinfo_documents(config) == expected

tests/test_quickstart.py

@@ -194,10 +194,6 @@ def test_quickstart_all_answers(tempdir):
     assert ns['man_pages'] == [
         ('contents', 'stasi', u'STASI™ Documentation',
          [u'Wolfgang Schäuble & G\'Beckstein'], 1)]
-    assert ns['texinfo_documents'] == [
-        ('contents', 'STASI', u'STASI™ Documentation',
-         u'Wolfgang Schäuble & G\'Beckstein', 'STASI',
-         'One line description of project.', 'Miscellaneous')]
 
     assert (tempdir / 'build').isdir()
     assert (tempdir / 'source' / '.static').isdir()
@@ -268,7 +264,6 @@ def test_default_filename(tempdir):
     execfile_(conffile, ns)
     assert ns['latex_documents'][0][1] == 'sphinx.tex'
     assert ns['man_pages'][0][1] == 'sphinx'
-    assert ns['texinfo_documents'][0][1] == 'sphinx'
 
 
 def test_extensions(tempdir):