Sphinx 8.1.2__py3-none-any.whl → 8.2.0__py3-none-any.whl

sphinx/ext/apidoc/_cli.py

@@ -0,0 +1,356 @@
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import locale
+import re
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import sphinx.locale
+from sphinx import __display_version__
+from sphinx.cmd.quickstart import EXTENSIONS
+from sphinx.ext.apidoc._generate import create_modules_toc_file, recurse_tree
+from sphinx.ext.apidoc._shared import LOGGER, ApidocOptions, _remove_old_files
+from sphinx.locale import __
+from sphinx.util.osutil import ensuredir
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from typing import Any
+
+
+def get_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        usage='%(prog)s [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN, ...]',
+        epilog=__('For more information, visit <https://www.sphinx-doc.org/>.'),
+        description=__("""
+Look recursively in <MODULE_PATH> for Python modules and packages and create
+one reST file with automodule directives per package in the <OUTPUT_PATH>.
+
+The <EXCLUDE_PATTERN>s can be file and/or directory patterns that will be
+excluded from generation.
+
+Note: By default this script will not overwrite already created files."""),
+    )
+
+    parser.add_argument(
+        '--version',
+        action='version',
+        dest='show_version',
+        version=f'%(prog)s {__display_version__}',
+    )
+
+    parser.add_argument('module_path', help=__('path to module to document'))
+    parser.add_argument(
+        'exclude_pattern',
+        nargs='*',
+        help=__(
+            'fnmatch-style file and/or directory patterns to exclude from generation'
+        ),
+    )
+
+    parser.add_argument(
+        '-o',
+        '--output-dir',
+        action='store',
+        dest='dest_dir',
+        required=True,
+        help=__('directory to place all output'),
+    )
+    parser.add_argument(
+        '-q',
+        action='store_true',
+        dest='quiet',
+        help=__('no output on stdout, just warnings on stderr'),
+    )
+    parser.add_argument(
+        '-d',
+        '--maxdepth',
+        action='store',
+        dest='max_depth',
+        type=int,
+        default=4,
+        help=__('maximum depth of submodules to show in the TOC (default: 4)'),
+    )
+    parser.add_argument(
+        '-f',
+        '--force',
+        action='store_true',
+        dest='force',
+        help=__('overwrite existing files'),
+    )
+    parser.add_argument(
+        '-l',
+        '--follow-links',
+        action='store_true',
+        dest='follow_links',
+        default=False,
+        help=__(
+            'follow symbolic links. Powerful when combined with collective.recipe.omelette.'
+        ),
+    )
+    parser.add_argument(
+        '-n',
+        '--dry-run',
+        action='store_true',
+        dest='dry_run',
+        help=__('run the script without creating files'),
+    )
+    parser.add_argument(
+        '-e',
+        '--separate',
+        action='store_true',
+        dest='separate_modules',
+        help=__('put documentation for each module on its own page'),
+    )
+    parser.add_argument(
+        '-P',
+        '--private',
+        action='store_true',
+        dest='include_private',
+        help=__('include "_private" modules'),
+    )
+    parser.add_argument(
+        '--tocfile',
+        action='store',
+        dest='toc_file',
+        default='modules',
+        help=__('filename of table of contents (default: modules)'),
+    )
+    parser.add_argument(
+        '-T',
+        '--no-toc',
+        action='store_false',
+        dest='toc_file',
+        help=__("don't create a table of contents file"),
+    )
+    parser.add_argument(
+        '-E',
+        '--no-headings',
+        action='store_true',
+        dest='no_headings',
+        help=__(
+            "don't create headings for the module/package "
+            'packages (e.g. when the docstrings already '
+            'contain them)'
+        ),
+    )
+    parser.add_argument(
+        '-M',
+        '--module-first',
+        action='store_true',
+        dest='module_first',
+        help=__('put module documentation before submodule documentation'),
+    )
+    parser.add_argument(
+        '--implicit-namespaces',
+        action='store_true',
+        dest='implicit_namespaces',
+        help=__(
+            'interpret module paths according to PEP-0420 implicit namespaces specification'
+        ),
+    )
+    parser.add_argument(
+        '--automodule-options',
+        dest='automodule_options',
+        default='',
+        help=__(
+            'Comma-separated list of options to pass to automodule directive '
+            '(or use SPHINX_APIDOC_OPTIONS).'
+        ),
+    )
+    parser.add_argument(
+        '-s',
+        '--suffix',
+        action='store',
+        dest='suffix',
+        default='rst',
+        help=__('file suffix (default: rst)'),
+    )
+    exclusive_group = parser.add_mutually_exclusive_group()
+    exclusive_group.add_argument(
+        '--remove-old',
+        action='store_true',
+        dest='remove_old',
+        help=__(
+            'Remove existing files in the output directory that were not generated'
+        ),
+    )
+    exclusive_group.add_argument(
+        '-F',
+        '--full',
+        action='store_true',
+        dest='full',
+        help=__('generate a full project with sphinx-quickstart'),
+    )
+    parser.add_argument(
+        '-a',
+        '--append-syspath',
+        action='store_true',
+        dest='append_syspath',
+        help=__('append module_path to sys.path, used when --full is given'),
+    )
+    parser.add_argument(
+        '-H',
+        '--doc-project',
+        action='store',
+        dest='header',
+        help=__('project name (default: root module name)'),
+    )
+    parser.add_argument(
+        '-A',
+        '--doc-author',
+        action='store',
+        dest='author',
+        help=__('project author(s), used when --full is given'),
+    )
+    parser.add_argument(
+        '-V',
+        '--doc-version',
+        action='store',
+        dest='version',
+        help=__('project version, used when --full is given'),
+    )
+    parser.add_argument(
+        '-R',
+        '--doc-release',
+        action='store',
+        dest='release',
+        help=__(
+            'project release, used when --full is given, defaults to --doc-version'
+        ),
+    )
+
+    group = parser.add_argument_group(__('extension options'))
+    group.add_argument(
+        '--extensions',
+        metavar='EXTENSIONS',
+        dest='extensions',
+        action='append',
+        help=__('enable arbitrary extensions, used when --full is given'),
+    )
+    for ext in EXTENSIONS:
+        group.add_argument(
+            f'--ext-{ext}',
+            action='append_const',
+            const=f'sphinx.ext.{ext}',
+            dest='extensions',
+            help=__('enable %s extension, used when --full is given') % ext,
+        )
+
+    group = parser.add_argument_group(__('Project templating'))
+    group.add_argument(
+        '-t',
+        '--templatedir',
+        metavar='TEMPLATEDIR',
+        dest='template_dir',
+        help=__('template directory for template files'),
+    )
+
+    return parser
+
+
+def main(argv: Sequence[str] = (), /) -> int:
+    """Run the apidoc CLI."""
+    locale.setlocale(locale.LC_ALL, '')
+    sphinx.locale.init_console()
+
+    opts = _parse_args(argv)
+    rootpath = opts.module_path
+    excludes = tuple(
+        re.compile(fnmatch.translate(str(Path(exclude).resolve())))
+        for exclude in dict.fromkeys(opts.exclude_pattern)
+    )
+
+    written_files, modules = recurse_tree(rootpath, excludes, opts, opts.template_dir)
+
+    if opts.full:
+        _full_quickstart(opts, modules=modules)
+    elif opts.toc_file:
+        written_files.append(
+            create_modules_toc_file(modules, opts, opts.toc_file, opts.template_dir)
+        )
+
+    if opts.remove_old and not opts.dry_run:
+        _remove_old_files(written_files, opts.dest_dir, opts.suffix)
+
+    return 0
+
+
+def _parse_args(argv: Sequence[str], /) -> ApidocOptions:
+    parser = get_parser()
+    args = parser.parse_args(argv or sys.argv[1:])
+
+    # normalise options
+
+    args.module_path = root_path = Path(args.module_path).resolve()
+    args.dest_dir = Path(args.dest_dir)
+    if not root_path.is_dir():
+        LOGGER.error(__('%s is not a directory.'), root_path)
+        raise SystemExit(1)
+
+    if args.header is None:
+        args.header = root_path.name
+    args.suffix = args.suffix.removeprefix('.')
+
+    if not args.dry_run:
+        ensuredir(args.dest_dir)
+
+    if not args.automodule_options:
+        args.automodule_options = frozenset()
+    elif isinstance(args.automodule_options, str):
+        args.automodule_options = frozenset(args.automodule_options.split(','))
+
+    return ApidocOptions(**args.__dict__)
+
+
+def _full_quickstart(opts: ApidocOptions, /, *, modules: list[str]) -> None:
+    from sphinx.cmd import quickstart as qs
+
+    modules.sort()
+    prev_module = ''
+    text = ''
+    for module in modules:
+        if module.startswith(prev_module + '.'):
+            continue
+        prev_module = module
+        text += f'   {module}\n'
+    d: dict[str, Any] = {
+        'path': str(opts.dest_dir),
+        'sep': False,
+        'dot': '_',
+        'project': opts.header,
+        'author': opts.author or 'Author',
+        'version': opts.version or '',
+        'release': opts.release or opts.version or '',
+        'suffix': '.' + opts.suffix,
+        'master': 'index',
+        'epub': True,
+        'extensions': [
+            'sphinx.ext.autodoc',
+            'sphinx.ext.viewcode',
+            'sphinx.ext.todo',
+        ],
+        'makefile': True,
+        'batchfile': True,
+        'make_mode': True,
+        'mastertocmaxdepth': opts.max_depth,
+        'mastertoctree': text,
+        'language': 'en',
+        'module_path': str(opts.module_path),
+        'append_syspath': opts.append_syspath,
+    }
+    if opts.extensions:
+        d['extensions'].extend(opts.extensions)
+    if opts.quiet:
+        d['quiet'] = True
+
+    for ext in d['extensions'][:]:
+        if ',' in ext:
+            d['extensions'].remove(ext)
+            d['extensions'].extend(ext.split(','))
+
+    if not opts.dry_run:
+        qs.generate(d, silent=True, overwrite=opts.force, templatedir=opts.template_dir)

sphinx/ext/apidoc/_extension.py

@@ -0,0 +1,262 @@
+"""Sphinx extension for auto-generating API documentation."""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from sphinx._cli.util.colour import bold
+from sphinx.ext.apidoc._generate import create_modules_toc_file, recurse_tree
+from sphinx.ext.apidoc._shared import (
+    LOGGER,
+    ApidocDefaults,
+    ApidocOptions,
+    _remove_old_files,
+)
+from sphinx.locale import __
+
+if TYPE_CHECKING:
+    from collections.abc import Collection, Sequence
+    from typing import Any
+
+    from sphinx.application import Sphinx
+
+_BOOL_KEYS = frozenset({
+    'follow_links',
+    'separate_modules',
+    'include_private',
+    'no_headings',
+    'module_first',
+    'implicit_namespaces',
+})
+_ALLOWED_KEYS = _BOOL_KEYS | frozenset({
+    'path',
+    'destination',
+    'exclude_patterns',
+    'automodule_options',
+    'max_depth',
+})
+
+
+def run_apidoc(app: Sphinx) -> None:
+    """Run the apidoc extension."""
+    defaults = ApidocDefaults.from_config(app.config)
+    apidoc_modules: Sequence[dict[str, Any]] = app.config.apidoc_modules
+    srcdir: Path = app.srcdir
+    confdir: Path = app.confdir
+
+    LOGGER.info(bold(__('Running apidoc')))
+
+    module_options: dict[str, Any]
+    for i, module_options in enumerate(apidoc_modules):
+        _run_apidoc_module(
+            i,
+            options=module_options,
+            defaults=defaults,
+            srcdir=srcdir,
+            confdir=confdir,
+        )
+
+
+def _run_apidoc_module(
+    i: int,
+    *,
+    options: dict[str, Any],
+    defaults: ApidocDefaults,
+    srcdir: Path,
+    confdir: Path,
+) -> None:
+    """Run apidoc for a single module."""
+    args = _parse_module_options(
+        i, options=options, defaults=defaults, srcdir=srcdir, confdir=confdir
+    )
+    if args is None:
+        return
+
+    exclude_patterns_compiled: list[re.Pattern[str]] = [
+        re.compile(fnmatch.translate(exclude)) for exclude in args.exclude_pattern
+    ]
+
+    written_files, modules = recurse_tree(
+        args.module_path, exclude_patterns_compiled, args, args.template_dir
+    )
+    if args.toc_file:
+        written_files.append(
+            create_modules_toc_file(modules, args, args.toc_file, args.template_dir)
+        )
+    if args.remove_old:
+        _remove_old_files(written_files, args.dest_dir, args.suffix)
+
+
+def _parse_module_options(
+    i: int,
+    *,
+    options: dict[str, Any],
+    defaults: ApidocDefaults,
+    srcdir: Path,
+    confdir: Path,
+) -> ApidocOptions | None:
+    if not isinstance(options, dict):
+        LOGGER.warning(__('apidoc_modules item %i must be a dict'), i, type='apidoc')
+        return None
+
+    # module path should be absolute or relative to the conf directory
+    try:
+        path = Path(options['path'])
+    except KeyError:
+        LOGGER.warning(
+            __("apidoc_modules item %i must have a 'path' key"), i, type='apidoc'
+        )
+        return None
+    except TypeError:
+        LOGGER.warning(
+            __("apidoc_modules item %i 'path' must be a string"), i, type='apidoc'
+        )
+        return None
+    module_path = confdir / path
+    if not module_path.is_dir():
+        LOGGER.warning(
+            __("apidoc_modules item %i 'path' is not an existing folder: %s"),
+            i,
+            module_path,
+            type='apidoc',
+        )
+        return None
+
+    # destination path should be relative to the source directory
+    try:
+        destination = Path(options['destination'])
+    except KeyError:
+        LOGGER.warning(
+            __("apidoc_modules item %i must have a 'destination' key"),
+            i,
+            type='apidoc',
+        )
+        return None
+    except TypeError:
+        LOGGER.warning(
+            __("apidoc_modules item %i 'destination' must be a string"),
+            i,
+            type='apidoc',
+        )
+        return None
+    if destination.is_absolute():
+        LOGGER.warning(
+            __("apidoc_modules item %i 'destination' should be a relative path"),
+            i,
+            type='apidoc',
+        )
+        return None
+    dest_path = srcdir / destination
+    try:
+        dest_path.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        LOGGER.warning(
+            __('apidoc_modules item %i cannot create destination directory: %s'),
+            i,
+            exc.strerror,
+            type='apidoc',
+        )
+        return None
+
+    # exclude patterns should be absolute or relative to the conf directory
+    exclude_patterns: list[str] = [
+        str(confdir / pattern)
+        for pattern in _check_collection_of_strings(
+            i, options, key='exclude_patterns', default=defaults.exclude_patterns
+        )
+    ]
+
+    # TODO template_dir
+
+    max_depth = defaults.max_depth
+    if 'max_depth' in options:
+        if not isinstance(options['max_depth'], int):
+            LOGGER.warning(
+                __("apidoc_modules item %i '%s' must be an int"),
+                i,
+                'max_depth',
+                type='apidoc',
+            )
+        else:
+            max_depth = options['max_depth']
+
+    bool_options: dict[str, bool] = {}
+    for key in sorted(_BOOL_KEYS):
+        if key not in options:
+            bool_options[key] = getattr(defaults, key)
+        elif not isinstance(options[key], bool):
+            LOGGER.warning(
+                __("apidoc_modules item %i '%s' must be a boolean"),
+                i,
+                key,
+                type='apidoc',
+            )
+            bool_options[key] = getattr(defaults, key)
+        else:
+            bool_options[key] = options[key]
+
+    # TODO per-module automodule_options
+    automodule_options = frozenset(
+        _check_collection_of_strings(
+            i, options, key='automodule_options', default=defaults.automodule_options
+        )
+    )
+
+    if diff := options.keys() - _ALLOWED_KEYS:
+        LOGGER.warning(
+            __('apidoc_modules item %i has unexpected keys: %s'),
+            i,
+            ', '.join(sorted(diff)),
+            type='apidoc',
+        )
+
+    return ApidocOptions(
+        dest_dir=dest_path,
+        module_path=module_path,
+        exclude_pattern=exclude_patterns,
+        automodule_options=automodule_options,
+        max_depth=max_depth,
+        quiet=True,
+        follow_links=bool_options['follow_links'],
+        separate_modules=bool_options['separate_modules'],
+        include_private=bool_options['include_private'],
+        no_headings=bool_options['no_headings'],
+        module_first=bool_options['module_first'],
+        implicit_namespaces=bool_options['implicit_namespaces'],
+    )
+
+
+def _check_collection_of_strings(
+    index: int,
+    options: dict[str, Any],
+    *,
+    key: str,
+    default: Collection[str],
+) -> Collection[str]:
+    """Check that a key's value is a collection of strings in the options.
+
+    :returns: The value of the key, or None if invalid.
+    """
+    if key not in options:
+        return default
+    if not isinstance(options[key], list | tuple | set | frozenset):
+        LOGGER.warning(
+            __("apidoc_modules item %i '%s' must be a sequence"),
+            index,
+            key,
+            type='apidoc',
+        )
+        return default
+    for item in options[key]:
+        if not isinstance(item, str):
+            LOGGER.warning(
+                __("apidoc_modules item %i '%s' must contain strings"),
+                index,
+                key,
+                type='apidoc',
+            )
+            return default
+    return options[key]