Sphinx 8.0.2__py3-none-any.whl → 8.1.0__py3-none-any.whl

sphinx/cmd/quickstart.py

@@ -13,14 +13,15 @@ from typing import TYPE_CHECKING, Any
 # try to import readline, unix specific enhancement
 try:
     import readline
-    if TYPE_CHECKING and sys.platform == "win32":  # always false, for type checking
+
+    if TYPE_CHECKING and sys.platform == 'win32':  # always false, for type checking
         raise ImportError
     READLINE_AVAILABLE = True
     if readline.__doc__ and 'libedit' in readline.__doc__:
-        readline.parse_and_bind("bind ^I rl_complete")
+        readline.parse_and_bind('bind ^I rl_complete')
         USE_LIBEDIT = True
     else:
-        readline.parse_and_bind("tab: complete")
+        readline.parse_and_bind('tab: complete')
         USE_LIBEDIT = False
 except ImportError:
     READLINE_AVAILABLE = False
@@ -90,7 +91,7 @@ class ValidationError(Exception):
 def is_path(x: str) -> str:
     x = path.expanduser(x)
     if not path.isdir(x):
-        raise ValidationError(__("Please enter a valid path name."))
+        raise ValidationError(__('Please enter a valid path name.'))
     return x
 
 
@@ -106,7 +107,7 @@ def allow_empty(x: str) -> str:
 
 def nonempty(x: str) -> str:
     if not x:
-        raise ValidationError(__("Please enter some text."))
+        raise ValidationError(__('Please enter some text.'))
     return x
 
 
@@ -115,6 +116,7 @@ def choice(*l: str) -> Callable[[str], str]:
         if x not in l:
             raise ValidationError(__('Please enter one of %s.') % ', '.join(l))
         return x
+
     return val
 
 
@@ -135,7 +137,9 @@ def ok(x: str) -> str:
 
 
 def do_prompt(
-    text: str, default: str | None = None, validator: Callable[[str], Any] = nonempty,
+    text: str,
+    default: str | None = None,
+    validator: Callable[[str], Any] = nonempty,
 ) -> str | bool:
     while True:
         if default is not None:
@@ -205,10 +209,16 @@ def ask_user(d: dict[str, Any]) -> None:
     * makefile:  make Makefile
     * batchfile: make command file
     """
-    print(bold(__('Welcome to the Sphinx %s quickstart utility.')) % __display_version__)
+    print(
+        bold(__('Welcome to the Sphinx %s quickstart utility.')) % __display_version__
+    )
     print()
-    print(__('Please enter values for the following settings (just press Enter to\n'
-             'accept a default value, if one is given in brackets).'))
+    print(
+        __(
+            'Please enter values for the following settings (just press Enter to\n'
+            'accept a default value, if one is given in brackets).'
+        )
+    )
 
     if 'path' in d:
         print()
@@ -218,90 +228,146 @@ def ask_user(d: dict[str, Any]) -> None:
         print(__('Enter the root path for documentation.'))
         d['path'] = do_prompt(__('Root path for the documentation'), '.', is_path)
 
-    while path.isfile(path.join(d['path'], 'conf.py')) or \
-            path.isfile(path.join(d['path'], 'source', 'conf.py')):
+    while path.isfile(path.join(d['path'], 'conf.py')) or path.isfile(
+        path.join(d['path'], 'source', 'conf.py')
+    ):
         print()
-        print(bold(__('Error: an existing conf.py has been found in the '
-                      'selected root path.')))
+        print(
+            bold(
+                __(
+                    'Error: an existing conf.py has been found in the '
+                    'selected root path.'
+                )
+            )
+        )
         print(__('sphinx-quickstart will not overwrite existing Sphinx projects.'))
         print()
-        d['path'] = do_prompt(__('Please enter a new root path (or just Enter to exit)'),
-                              '', is_path_or_empty)
+        d['path'] = do_prompt(
+            __('Please enter a new root path (or just Enter to exit)'),
+            '',
+            is_path_or_empty,
+        )
         if not d['path']:
             raise SystemExit(1)
 
     if 'sep' not in d:
         print()
-        print(__('You have two options for placing the build directory for Sphinx output.\n'
-                 'Either, you use a directory "_build" within the root path, or you separate\n'
-                 '"source" and "build" directories within the root path.'))
-        d['sep'] = do_prompt(__('Separate source and build directories (y/n)'), 'n', boolean)
+        print(
+            __(
+                'You have two options for placing the build directory for Sphinx output.\n'
+                'Either, you use a directory "_build" within the root path, or you separate\n'
+                '"source" and "build" directories within the root path.'
+            )
+        )
+        d['sep'] = do_prompt(
+            __('Separate source and build directories (y/n)'), 'n', boolean
+        )
 
     if 'dot' not in d:
         print()
-        print(__('Inside the root directory, two more directories will be created; "_templates"\n'      # NoQA: E501
-                 'for custom HTML templates and "_static" for custom stylesheets and other static\n'    # NoQA: E501
-                 'files. You can enter another prefix (such as ".") to replace the underscore.'))       # NoQA: E501
+        print(
+            __(
+                'Inside the root directory, two more directories will be created; "_templates"\n'  # NoQA: E501
+                'for custom HTML templates and "_static" for custom stylesheets and other static\n'  # NoQA: E501
+                'files. You can enter another prefix (such as ".") to replace the underscore.'
+            )
+        )  # NoQA: E501
         d['dot'] = do_prompt(__('Name prefix for templates and static dir'), '_', ok)
 
     if 'project' not in d:
         print()
-        print(__('The project name will occur in several places in the built documentation.'))
+        print(
+            __(
+                'The project name will occur in several places in the built documentation.'
+            )
+        )
         d['project'] = do_prompt(__('Project name'))
     if 'author' not in d:
         d['author'] = do_prompt(__('Author name(s)'))
 
     if 'version' not in d:
         print()
-        print(__('Sphinx has the notion of a "version" and a "release" for the\n'
-                 'software. Each version can have multiple releases. For example, for\n'
-                 'Python the version is something like 2.5 or 3.0, while the release is\n'
-                 "something like 2.5.1 or 3.0a1. If you don't need this dual structure,\n"
-                 'just set both to the same value.'))
+        print(
+            __(
+                'Sphinx has the notion of a "version" and a "release" for the\n'
+                'software. Each version can have multiple releases. For example, for\n'
+                'Python the version is something like 2.5 or 3.0, while the release is\n'
+                "something like 2.5.1 or 3.0a1. If you don't need this dual structure,\n"
+                'just set both to the same value.'
+            )
+        )
         d['version'] = do_prompt(__('Project version'), '', allow_empty)
     if 'release' not in d:
         d['release'] = do_prompt(__('Project release'), d['version'], allow_empty)
 
     if 'language' not in d:
         print()
-        print(__(
-            'If the documents are to be written in a language other than English,\n'
-            'you can select a language here by its language code. Sphinx will then\n'
-            'translate text that it generates into that language.\n'
-            '\n'
-            'For a list of supported codes, see\n'
-            'https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.',
-        ))
+        print(
+            __(
+                'If the documents are to be written in a language other than English,\n'
+                'you can select a language here by its language code. Sphinx will then\n'
+                'translate text that it generates into that language.\n'
+                '\n'
+                'For a list of supported codes, see\n'
+                'https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.',
+            )
+        )
         d['language'] = do_prompt(__('Project language'), 'en')
         if d['language'] == 'en':
             d['language'] = None
 
     if 'suffix' not in d:
         print()
-        print(__('The file name suffix for source files. Commonly, this is either ".txt"\n'
-                 'or ".rst". Only files with this suffix are considered documents.'))
+        print(
+            __(
+                'The file name suffix for source files. Commonly, this is either ".txt"\n'
+                'or ".rst". Only files with this suffix are considered documents.'
+            )
+        )
         d['suffix'] = do_prompt(__('Source file suffix'), '.rst', suffix)
 
     if 'master' not in d:
         print()
-        print(__('One document is special in that it is considered the top node of the\n'
-                 '"contents tree", that is, it is the root of the hierarchical structure\n'
-                 'of the documents. Normally, this is "index", but if your "index"\n'
-                 'document is a custom template, you can also set this to another filename.'))
-        d['master'] = do_prompt(__('Name of your master document (without suffix)'), 'index')
-
-    while path.isfile(path.join(d['path'], d['master'] + d['suffix'])) or \
-            path.isfile(path.join(d['path'], 'source', d['master'] + d['suffix'])):
+        print(
+            __(
+                'One document is special in that it is considered the top node of the\n'
+                '"contents tree", that is, it is the root of the hierarchical structure\n'
+                'of the documents. Normally, this is "index", but if your "index"\n'
+                'document is a custom template, you can also set this to another filename.'
+            )
+        )
+        d['master'] = do_prompt(
+            __('Name of your master document (without suffix)'), 'index'
+        )
+
+    while (
+        path.isfile(path.join(d['path'], d['master'] + d['suffix']))
+        or path.isfile(path.join(d['path'], 'source', d['master'] + d['suffix']))
+    ):  # fmt: skip
         print()
-        print(bold(__('Error: the master file %s has already been found in the '
-                      'selected root path.') % (d['master'] + d['suffix'])))
+        print(
+            bold(
+                __(
+                    'Error: the master file %s has already been found in the '
+                    'selected root path.'
+                )
+                % (d['master'] + d['suffix'])
+            )
+        )
         print(__('sphinx-quickstart will not overwrite the existing file.'))
         print()
-        d['master'] = do_prompt(__('Please enter a new file name, or rename the '
-                                   'existing file and press Enter'), d['master'])
+        d['master'] = do_prompt(
+            __(
+                'Please enter a new file name, or rename the '
+                'existing file and press Enter'
+            ),
+            d['master'],
+        )
 
     if 'extensions' not in d:
-        print(__('Indicate which of the following Sphinx extensions should be enabled:'))
+        print(
+            __('Indicate which of the following Sphinx extensions should be enabled:')
+        )
         d['extensions'] = []
         for name, description in EXTENSIONS.items():
             if do_prompt(f'{name}: {description} (y/n)', 'n', boolean):
@@ -309,19 +375,29 @@ def ask_user(d: dict[str, Any]) -> None:
 
         # Handle conflicting options
         if {'sphinx.ext.imgmath', 'sphinx.ext.mathjax'}.issubset(d['extensions']):
-            print(__('Note: imgmath and mathjax cannot be enabled at the same time. '
-                     'imgmath has been deselected.'))
+            print(
+                __(
+                    'Note: imgmath and mathjax cannot be enabled at the same time. '
+                    'imgmath has been deselected.'
+                )
+            )
             d['extensions'].remove('sphinx.ext.imgmath')
 
     if 'makefile' not in d:
         print()
-        print(__('A Makefile and a Windows command file can be generated for you so that you\n'
-                 "only have to run e.g. `make html' instead of invoking sphinx-build\n"
-                 'directly.'))
+        print(
+            __(
+                'A Makefile and a Windows command file can be generated for you so that you\n'
+                "only have to run e.g. `make html' instead of invoking sphinx-build\n"
+                'directly.'
+            )
+        )
         d['makefile'] = do_prompt(__('Create Makefile? (y/n)'), 'y', boolean)
 
     if 'batchfile' not in d:
-        d['batchfile'] = do_prompt(__('Create Windows command file? (y/n)'), 'y', boolean)
+        d['batchfile'] = do_prompt(
+            __('Create Windows command file? (y/n)'), 'y', boolean
+        )
     print()
 
 
@@ -345,7 +421,7 @@ def generate(
     d.setdefault('extensions', [])
     d['copyright'] = time.strftime('%Y') + ', ' + d['author']
 
-    d["path"] = os.path.abspath(d['path'])
+    d['path'] = os.path.abspath(d['path'])
     ensuredir(d['path'])
 
     srcdir = path.join(d['path'], 'source') if d['sep'] else d['path']
@@ -356,10 +432,14 @@ def generate(
         d['exclude_patterns'] = ''
     else:
         builddir = path.join(srcdir, d['dot'] + 'build')
-        exclude_patterns = map(repr, [
-            d['dot'] + 'build',
-            'Thumbs.db', '.DS_Store',
-        ])
+        exclude_patterns = map(
+            repr,
+            [
+                d['dot'] + 'build',
+                'Thumbs.db',
+                '.DS_Store',
+            ],
+        )
         d['exclude_patterns'] = ', '.join(exclude_patterns)
     ensuredir(builddir)
     ensuredir(path.join(srcdir, d['dot'] + 'templates'))
@@ -377,17 +457,16 @@ def generate(
 
     conf_path = os.path.join(templatedir, 'conf.py.jinja') if templatedir else None
     if not conf_path or not path.isfile(conf_path):
-        conf_path = os.path.join(package_dir, 'templates', 'quickstart', 'conf.py.jinja')
-    with open(conf_path, encoding="utf-8") as f:
+        conf_path = os.path.join(
+            package_dir, 'templates', 'quickstart', 'conf.py.jinja'
+        )
+    with open(conf_path, encoding='utf-8') as f:
         conf_text = f.read()
 
     write_file(path.join(srcdir, 'conf.py'), template.render_string(conf_text, d))
 
     masterfile = path.join(srcdir, d['master'] + d['suffix'])
     if template._has_custom_template('quickstart/master_doc.rst.jinja'):
-        msg = ('A custom template `master_doc.rst.jinja` found. It has been renamed to '
-               '`root_doc.rst.jinja`.  Please rename it on your project too.')
-        print(colorize('red', msg))
         write_file(masterfile, template.render('quickstart/master_doc.rst.jinja', d))
     else:
         write_file(masterfile, template.render('quickstart/root_doc.rst.jinja', d))
@@ -399,30 +478,50 @@ def generate(
         d['rsrcdir'] = 'source' if d['sep'] else '.'
         d['rbuilddir'] = 'build' if d['sep'] else d['dot'] + 'build'
         # use binary mode, to avoid writing \r\n on Windows
-        write_file(path.join(d['path'], 'Makefile'),
-                   template.render(makefile_template, d), '\n')
+        write_file(
+            path.join(d['path'], 'Makefile'),
+            template.render(makefile_template, d),
+            '\n',
+        )
 
     if d['batchfile'] is True:
         d['rsrcdir'] = 'source' if d['sep'] else '.'
         d['rbuilddir'] = 'build' if d['sep'] else d['dot'] + 'build'
-        write_file(path.join(d['path'], 'make.bat'),
-                   template.render(batchfile_template, d), '\r\n')
+        write_file(
+            path.join(d['path'], 'make.bat'),
+            template.render(batchfile_template, d),
+            '\r\n',
+        )
 
     if silent:
         return
     print()
     print(bold(__('Finished: An initial directory structure has been created.')))
     print()
-    print(__('You should now populate your master file %s and create other documentation\n'
-             'source files. ') % masterfile, end='')
+    print(
+        __(
+            'You should now populate your master file %s and create other documentation\n'
+            'source files. '
+        )
+        % masterfile,
+        end='',
+    )
     if d['makefile'] or d['batchfile']:
-        print(__('Use the Makefile to build the docs, like so:\n'
-                 '   make builder'))
+        print(__('Use the Makefile to build the docs, like so:\n' '   make builder'))
     else:
-        print(__('Use the sphinx-build command to build the docs, like so:\n'
-                 '   sphinx-build -b builder %s %s') % (srcdir, builddir))
-    print(__('where "builder" is one of the supported builders, '
-             'e.g. html, latex or linkcheck.'))
+        print(
+            __(
+                'Use the sphinx-build command to build the docs, like so:\n'
+                '   sphinx-build -b builder %s %s'
+            )
+            % (srcdir, builddir)
+        )
+    print(
+        __(
+            'where "builder" is one of the supported builders, '
+            'e.g. html, latex or linkcheck.'
+        )
+    )
     print()
 
 
@@ -454,83 +553,166 @@ def valid_dir(d: dict[str, Any]) -> bool:
 
 def get_parser() -> argparse.ArgumentParser:
     description = __(
-        "\n"
-        "Generate required files for a Sphinx project.\n"
-        "\n"
-        "sphinx-quickstart is an interactive tool that asks some questions about your\n"
-        "project and then generates a complete documentation directory and sample\n"
-        "Makefile to be used with sphinx-build.\n",
+        '\n'
+        'Generate required files for a Sphinx project.\n'
+        '\n'
+        'sphinx-quickstart is an interactive tool that asks some questions about your\n'
+        'project and then generates a complete documentation directory and sample\n'
+        'Makefile to be used with sphinx-build.\n',
     )
     parser = argparse.ArgumentParser(
         usage='%(prog)s [OPTIONS] <PROJECT_DIR>',
-        epilog=__("For more information, visit <https://www.sphinx-doc.org/>."),
-        description=description)
+        epilog=__('For more information, visit <https://www.sphinx-doc.org/>.'),
+        description=description,
+    )
 
-    parser.add_argument('-q', '--quiet', action='store_true', dest='quiet',
-                        default=None,
-                        help=__('quiet mode'))
-    parser.add_argument('--version', action='version', dest='show_version',
-                        version='%%(prog)s %s' % __display_version__)
+    parser.add_argument(
+        '-q',
+        '--quiet',
+        action='store_true',
+        dest='quiet',
+        default=None,
+        help=__('quiet mode'),
+    )
+    parser.add_argument(
+        '--version',
+        action='version',
+        dest='show_version',
+        version='%%(prog)s %s' % __display_version__,
+    )
 
-    parser.add_argument('path', metavar='PROJECT_DIR', default='.', nargs='?',
-                        help=__('project root'))
+    parser.add_argument(
+        'path', metavar='PROJECT_DIR', default='.', nargs='?', help=__('project root')
+    )
 
     group = parser.add_argument_group(__('Structure options'))
-    group.add_argument('--sep', action='store_true', dest='sep', default=None,
-                       help=__('if specified, separate source and build dirs'))
-    group.add_argument('--no-sep', action='store_false', dest='sep',
-                       help=__('if specified, create build dir under source dir'))
-    group.add_argument('--dot', metavar='DOT', default='_',
-                       help=__('replacement for dot in _templates etc.'))
+    group.add_argument(
+        '--sep',
+        action='store_true',
+        dest='sep',
+        default=None,
+        help=__('if specified, separate source and build dirs'),
+    )
+    group.add_argument(
+        '--no-sep',
+        action='store_false',
+        dest='sep',
+        help=__('if specified, create build dir under source dir'),
+    )
+    group.add_argument(
+        '--dot',
+        metavar='DOT',
+        default='_',
+        help=__('replacement for dot in _templates etc.'),
+    )
 
     group = parser.add_argument_group(__('Project basic options'))
-    group.add_argument('-p', '--project', metavar='PROJECT', dest='project',
-                       help=__('project name'))
-    group.add_argument('-a', '--author', metavar='AUTHOR', dest='author',
-                       help=__('author names'))
-    group.add_argument('-v', metavar='VERSION', dest='version', default='',
-                       help=__('version of project'))
-    group.add_argument('-r', '--release', metavar='RELEASE', dest='release',
-                       help=__('release of project'))
-    group.add_argument('-l', '--language', metavar='LANGUAGE', dest='language',
-                       help=__('document language'))
-    group.add_argument('--suffix', metavar='SUFFIX', default='.rst',
-                       help=__('source file suffix'))
-    group.add_argument('--master', metavar='MASTER', default='index',
-                       help=__('master document name'))
-    group.add_argument('--epub', action='store_true', default=False,
-                       help=__('use epub'))
+    group.add_argument(
+        '-p', '--project', metavar='PROJECT', dest='project', help=__('project name')
+    )
+    group.add_argument(
+        '-a', '--author', metavar='AUTHOR', dest='author', help=__('author names')
+    )
+    group.add_argument(
+        '-v',
+        metavar='VERSION',
+        dest='version',
+        default='',
+        help=__('version of project'),
+    )
+    group.add_argument(
+        '-r',
+        '--release',
+        metavar='RELEASE',
+        dest='release',
+        help=__('release of project'),
+    )
+    group.add_argument(
+        '-l',
+        '--language',
+        metavar='LANGUAGE',
+        dest='language',
+        help=__('document language'),
+    )
+    group.add_argument(
+        '--suffix', metavar='SUFFIX', default='.rst', help=__('source file suffix')
+    )
+    group.add_argument(
+        '--master', metavar='MASTER', default='index', help=__('master document name')
+    )
+    group.add_argument(
+        '--epub', action='store_true', default=False, help=__('use epub')
+    )
 
     group = parser.add_argument_group(__('Extension options'))
     for ext in EXTENSIONS:
-        group.add_argument('--ext-%s' % ext, action='append_const',
-                           const='sphinx.ext.%s' % ext, dest='extensions',
-                           help=__('enable %s extension') % ext)
-    group.add_argument('--extensions', metavar='EXTENSIONS', dest='extensions',
-                       action='append', help=__('enable arbitrary extensions'))
+        group.add_argument(
+            '--ext-%s' % ext,
+            action='append_const',
+            const='sphinx.ext.%s' % ext,
+            dest='extensions',
+            help=__('enable %s extension') % ext,
+        )
+    group.add_argument(
+        '--extensions',
+        metavar='EXTENSIONS',
+        dest='extensions',
+        action='append',
+        help=__('enable arbitrary extensions'),
+    )
 
     group = parser.add_argument_group(__('Makefile and Batchfile creation'))
-    group.add_argument('--makefile', action='store_true', dest='makefile', default=True,
-                       help=__('create makefile'))
-    group.add_argument('--no-makefile', action='store_false', dest='makefile',
-                       help=__('do not create makefile'))
-    group.add_argument('--batchfile', action='store_true', dest='batchfile', default=True,
-                       help=__('create batchfile'))
-    group.add_argument('--no-batchfile', action='store_false',
-                       dest='batchfile',
-                       help=__('do not create batchfile'))
+    group.add_argument(
+        '--makefile',
+        action='store_true',
+        dest='makefile',
+        default=True,
+        help=__('create makefile'),
+    )
+    group.add_argument(
+        '--no-makefile',
+        action='store_false',
+        dest='makefile',
+        help=__('do not create makefile'),
+    )
+    group.add_argument(
+        '--batchfile',
+        action='store_true',
+        dest='batchfile',
+        default=True,
+        help=__('create batchfile'),
+    )
+    group.add_argument(
+        '--no-batchfile',
+        action='store_false',
+        dest='batchfile',
+        help=__('do not create batchfile'),
+    )
     # --use-make-mode is a no-op from Sphinx 8.
-    group.add_argument('-m', '--use-make-mode', action='store_true',
-                       dest='make_mode', default=True,
-                       help=__('use make-mode for Makefile/make.bat'))
+    group.add_argument(
+        '-m',
+        '--use-make-mode',
+        action='store_true',
+        dest='make_mode',
+        default=True,
+        help=__('use make-mode for Makefile/make.bat'),
+    )
 
     group = parser.add_argument_group(__('Project templating'))
-    group.add_argument('-t', '--templatedir', metavar='TEMPLATEDIR',
-                       dest='templatedir',
-                       help=__('template directory for template files'))
-    group.add_argument('-d', metavar='NAME=VALUE', action='append',
-                       dest='variables',
-                       help=__('define a template variable'))
+    group.add_argument(
+        '-t',
+        '--templatedir',
+        metavar='TEMPLATEDIR',
+        dest='templatedir',
+        help=__('template directory for template files'),
+    )
+    group.add_argument(
+        '-d',
+        metavar='NAME=VALUE',
+        action='append',
+        dest='variables',
+        help=__('define a template variable'),
+    )
 
     return parser
 
@@ -563,8 +745,12 @@ def main(argv: Sequence[str] = (), /) -> int:
     try:
         if 'quiet' in d:
             if not {'project', 'author'}.issubset(d):
-                print(__('"quiet" is specified, but any of "project" or '
-                         '"author" is not specified.'))
+                print(
+                    __(
+                        '"quiet" is specified, but any of "project" or '
+                        '"author" is not specified.'
+                    )
+                )
                 return 1
 
         if {'quiet', 'project', 'author'}.issubset(d):
@@ -577,10 +763,20 @@ def main(argv: Sequence[str] = (), /) -> int:
 
             if not valid_dir(d):
                 print()
-                print(bold(__('Error: specified path is not a directory, or sphinx'
-                              ' files already exist.')))
-                print(__('sphinx-quickstart only generate into a empty directory.'
-                         ' Please specify a new root path.'))
+                print(
+                    bold(
+                        __(
+                            'Error: specified path is not a directory, or sphinx'
+                            ' files already exist.'
+                        )
+                    )
+                )
+                print(
+                    __(
+                        'sphinx-quickstart only generate into a empty directory.'
+                        ' Please specify a new root path.'
+                    )
+                )
                 return 1
         else:
             ask_user(d)