Sphinx 8.1.3__py3-none-any.whl → 8.2.0rc1__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='destdir',
+        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='maxdepth',
+        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='followlinks',
+        default=False,
+        help=__(
+            'follow symbolic links. Powerful when combined with collective.recipe.omelette.'
+        ),
+    )
+    parser.add_argument(
+        '-n',
+        '--dry-run',
+        action='store_true',
+        dest='dryrun',
+        help=__('run the script without creating files'),
+    )
+    parser.add_argument(
+        '-e',
+        '--separate',
+        action='store_true',
+        dest='separatemodules',
+        help=__('put documentation for each module on its own page'),
+    )
+    parser.add_argument(
+        '-P',
+        '--private',
+        action='store_true',
+        dest='includeprivate',
+        help=__('include "_private" modules'),
+    )
+    parser.add_argument(
+        '--tocfile',
+        action='store',
+        dest='tocfile',
+        default='modules',
+        help=__('filename of table of contents (default: modules)'),
+    )
+    parser.add_argument(
+        '-T',
+        '--no-toc',
+        action='store_false',
+        dest='tocfile',
+        help=__("don't create a table of contents file"),
+    )
+    parser.add_argument(
+        '-E',
+        '--no-headings',
+        action='store_true',
+        dest='noheadings',
+        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='modulefirst',
+        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='templatedir',
+        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.templatedir)
+
+    if opts.full:
+        _full_quickstart(opts, modules=modules)
+    elif opts.tocfile:
+        written_files.append(
+            create_modules_toc_file(modules, opts, opts.tocfile, opts.templatedir)
+        )
+
+    if opts.remove_old and not opts.dryrun:
+        _remove_old_files(written_files, opts.destdir, 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.destdir = Path(args.destdir)
+    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.dryrun:
+        ensuredir(args.destdir)
+
+    if not args.automodule_options:
+        args.automodule_options = set()
+    elif isinstance(args.automodule_options, str):
+        args.automodule_options = set(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.destdir),
+        '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.maxdepth,
+        '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.dryrun:
+        qs.generate(d, silent=True, overwrite=opts.force, templatedir=opts.templatedir)

sphinx/ext/apidoc/_generate.py

@@ -0,0 +1,356 @@
+from __future__ import annotations
+
+import glob
+import os
+import os.path
+from importlib.machinery import EXTENSION_SUFFIXES
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from sphinx import package_dir
+from sphinx.ext.apidoc._shared import LOGGER
+from sphinx.locale import __
+from sphinx.util.osutil import FileAvoidWrite
+from sphinx.util.template import ReSTRenderer
+
+if TYPE_CHECKING:
+    import re
+    from collections.abc import Iterable, Iterator, Sequence
+
+    from sphinx.ext.apidoc._shared import ApidocOptions
+
+
+# automodule options
+if 'SPHINX_APIDOC_OPTIONS' in os.environ:
+    OPTIONS = set(os.environ['SPHINX_APIDOC_OPTIONS'].split(','))
+else:
+    OPTIONS = {
+        'members',
+        'undoc-members',
+        # 'inherited-members', # disabled because there's a bug in sphinx
+        'show-inheritance',
+    }
+
+PY_SUFFIXES = ('.py', '.pyx', *EXTENSION_SUFFIXES)
+
+template_dir = package_dir.joinpath('templates', 'apidoc')
+
+
+def is_initpy(filename: str | Path) -> bool:
+    """Check *filename* is __init__ file or not."""
+    basename = Path(filename).name
+    return any(
+        basename == '__init__' + suffix
+        for suffix in sorted(PY_SUFFIXES, key=len, reverse=True)
+    )
+
+
+def module_join(*modnames: str | None) -> str:
+    """Join module names with dots."""
+    return '.'.join(filter(None, modnames))
+
+
+def is_package_dir(
+    files: Iterable[Path | str] = (), *, dir_path: Path | None = None
+) -> bool:
+    """Check given *files* contains __init__ file."""
+    if files != ():
+        return any(map(is_initpy, files))
+    if dir_path is not None:
+        return any(map(is_initpy, dir_path.iterdir()))
+    return False
+
+
+def write_file(name: str, text: str, opts: ApidocOptions) -> Path:
+    """Write the output file for module/package <name>."""
+    fname = Path(opts.destdir, f'{name}.{opts.suffix}')
+    if opts.dryrun:
+        if not opts.quiet:
+            LOGGER.info(__('Would create file %s.'), fname)
+        return fname
+    if not opts.force and fname.is_file():
+        if not opts.quiet:
+            LOGGER.info(__('File %s already exists, skipping.'), fname)
+    else:
+        if not opts.quiet:
+            LOGGER.info(__('Creating file %s.'), fname)
+        with FileAvoidWrite(fname) as f:
+            f.write(text)
+    return fname
+
+
+def create_module_file(
+    package: str | None,
+    basename: str,
+    opts: ApidocOptions,
+    user_template_dir: str | os.PathLike[str] | None = None,
+) -> Path:
+    """Build the text of the file and write the file."""
+    options = set(OPTIONS if not opts.automodule_options else opts.automodule_options)
+    if opts.includeprivate:
+        options.add('private-members')
+
+    qualname = module_join(package, basename)
+    context = {
+        'show_headings': not opts.noheadings,
+        'basename': basename,
+        'qualname': qualname,
+        'automodule_options': sorted(options),
+    }
+    template_path: Sequence[str | os.PathLike[str]]
+    if user_template_dir is not None:
+        template_path = [user_template_dir, template_dir]
+    else:
+        template_path = [template_dir]
+    text = ReSTRenderer(template_path).render('module.rst.jinja', context)
+    return write_file(qualname, text, opts)
+
+
+def create_package_file(
+    root: str,
+    master_package: str | None,
+    subroot: str,
+    py_files: list[str],
+    opts: ApidocOptions,
+    subs: list[str],
+    is_namespace: bool,
+    excludes: Sequence[re.Pattern[str]] = (),
+    user_template_dir: str | os.PathLike[str] | None = None,
+) -> list[Path]:
+    """Build the text of the file and write the file.
+
+    Also create submodules if necessary.
+
+    :returns: list of written files
+    """
+    # build a list of sub packages (directories containing an __init__ file)
+    subpackages = [
+        module_join(master_package, subroot, pkgname)
+        for pkgname in subs
+        if not is_skipped_package(Path(root, pkgname), opts, excludes)
+    ]
+    # build a list of sub modules
+    submodules = [
+        sub.split('.')[0]
+        for sub in py_files
+        if not is_skipped_module(Path(root, sub), opts, excludes) and not is_initpy(sub)
+    ]
+    submodules = sorted(set(submodules))
+    submodules = [
+        module_join(master_package, subroot, modname) for modname in submodules
+    ]
+    options = OPTIONS.copy()
+    if opts.includeprivate:
+        options.add('private-members')
+
+    pkgname = module_join(master_package, subroot)
+    context = {
+        'pkgname': pkgname,
+        'subpackages': subpackages,
+        'submodules': submodules,
+        'is_namespace': is_namespace,
+        'modulefirst': opts.modulefirst,
+        'separatemodules': opts.separatemodules,
+        'automodule_options': sorted(options),
+        'show_headings': not opts.noheadings,
+        'maxdepth': opts.maxdepth,
+    }
+    if user_template_dir is not None:
+        template_path = [user_template_dir, template_dir]
+    else:
+        template_path = [template_dir]
+
+    written: list[Path] = []
+
+    text = ReSTRenderer(template_path).render('package.rst.jinja', context)
+    written.append(write_file(pkgname, text, opts))
+
+    if submodules and opts.separatemodules:
+        written.extend([
+            create_module_file(None, submodule, opts, user_template_dir)
+            for submodule in submodules
+        ])
+
+    return written
+
+
+def create_modules_toc_file(
+    modules: list[str],
+    opts: ApidocOptions,
+    name: str = 'modules',
+    user_template_dir: str | os.PathLike[str] | None = None,
+) -> Path:
+    """Create the module's index."""
+    modules.sort()
+    prev_module = ''
+    for module in modules.copy():
+        # look if the module is a subpackage and, if yes, ignore it
+        if module.startswith(prev_module + '.'):
+            modules.remove(module)
+        else:
+            prev_module = module
+
+    context = {
+        'header': opts.header,
+        'maxdepth': opts.maxdepth,
+        'docnames': modules,
+    }
+    template_path: Sequence[str | os.PathLike[str]]
+    if user_template_dir is not None:
+        template_path = [user_template_dir, template_dir]
+    else:
+        template_path = [template_dir]
+    text = ReSTRenderer(template_path).render('toc.rst.jinja', context)
+    return write_file(name, text, opts)
+
+
+def is_skipped_package(
+    dirname: str | Path, opts: ApidocOptions, excludes: Sequence[re.Pattern[str]] = ()
+) -> bool:
+    """Check if we want to skip this module."""
+    if not Path(dirname).is_dir():
+        return False
+
+    files = glob.glob(str(Path(dirname, '*.py')))  # NoQA: PTH207
+    regular_package = any(f for f in files if is_initpy(f))
+    if not regular_package and not opts.implicit_namespaces:
+        # *dirname* is not both a regular package and an implicit namespace package
+        return True
+
+    # Check there is some showable module inside package
+    return all(is_excluded(Path(dirname, f), excludes) for f in files)
+
+
+def is_skipped_module(
+    filename: str | Path, opts: ApidocOptions, _excludes: Sequence[re.Pattern[str]]
+) -> bool:
+    """Check if we want to skip this module."""
+    filename = Path(filename)
+    if not filename.exists():
+        # skip if the file doesn't exist
+        return True
+    # skip if the module has a "private" name
+    return filename.name.startswith('_') and not opts.includeprivate
+
+
+def walk(
+    root_path: str | Path,
+    excludes: Sequence[re.Pattern[str]],
+    opts: ApidocOptions,
+) -> Iterator[tuple[str, list[str], list[str]]]:
+    """Walk through the directory and list files and subdirectories up."""
+    for root, subs, files in os.walk(root_path, followlinks=opts.followlinks):
+        # document only Python module files (that aren't excluded)
+        files = sorted(
+            f
+            for f in files
+            if f.endswith(PY_SUFFIXES) and not is_excluded(Path(root, f), excludes)
+        )
+
+        # remove hidden ('.') and private ('_') directories, as well as
+        # excluded dirs
+        if opts.includeprivate:
+            exclude_prefixes: tuple[str, ...] = ('.',)
+        else:
+            exclude_prefixes = ('.', '_')
+
+        subs[:] = sorted(
+            sub
+            for sub in subs
+            if not sub.startswith(exclude_prefixes)
+            and not is_excluded(Path(root, sub), excludes)
+        )
+
+        yield root, subs, files
+
+
+def has_child_module(
+    root_path: str | Path, excludes: Sequence[re.Pattern[str]], opts: ApidocOptions
+) -> bool:
+    """Check the given directory contains child module/s (at least one)."""
+    return any(files for _root, _subs, files in walk(root_path, excludes, opts))
+
+
+def recurse_tree(
+    root_path: str | os.PathLike[str],
+    excludes: Sequence[re.Pattern[str]],
+    opts: ApidocOptions,
+    user_template_dir: str | os.PathLike[str] | None = None,
+) -> tuple[list[Path], list[str]]:
+    """Look for every file in the directory tree and create the corresponding
+    ReST files.
+    """
+    # check if the base directory is a package and get its name
+    root_path = Path(root_path)
+    if is_package_dir(dir_path=root_path) or opts.implicit_namespaces:
+        root_package = root_path.name
+    else:
+        # otherwise, the base is a directory with packages
+        root_package = None
+
+    toplevels = []
+    written_files = []
+    for root, subs, files in walk(root_path, excludes, opts):
+        is_pkg = is_package_dir(files)
+        is_namespace = not is_pkg and opts.implicit_namespaces
+        if is_pkg:
+            for f in files.copy():
+                if is_initpy(f):
+                    files.remove(f)
+                    files.insert(0, f)
+        elif root != str(root_path):
+            # only accept non-package at toplevel unless using implicit namespaces
+            if not opts.implicit_namespaces:
+                subs.clear()
+                continue
+
+        if is_pkg or is_namespace:
+            # we are in a package with something to document
+            if subs or len(files) > 1 or not is_skipped_package(root, opts):
+                subpackage = (
+                    root.removeprefix(str(root_path))
+                    .lstrip(os.path.sep)
+                    .replace(os.path.sep, '.')
+                )
+                # if this is not a namespace or
+                # a namespace and there is something there to document
+                if not is_namespace or has_child_module(root, excludes, opts):
+                    written_files.extend(
+                        create_package_file(
+                            root,
+                            root_package,
+                            subpackage,
+                            files,
+                            opts,
+                            subs,
+                            is_namespace,
+                            excludes,
+                            user_template_dir,
+                        )
+                    )
+                    toplevels.append(module_join(root_package, subpackage))
+        else:
+            # if we are at the root level, we don't require it to be a package
+            assert root == str(root_path)
+            assert root_package is None
+            for py_file in files:
+                if not is_skipped_module(Path(root_path, py_file), opts, excludes):
+                    module = py_file.split('.')[0]
+                    written_files.append(
+                        create_module_file(
+                            root_package, module, opts, user_template_dir
+                        )
+                    )
+                    toplevels.append(module)
+
+    return written_files, toplevels
+
+
+def is_excluded(root: str | Path, excludes: Sequence[re.Pattern[str]]) -> bool:
+    """Check if the directory is in the exclude list.
+
+    Note: by having trailing slashes, we avoid common prefix issues, like
+          e.g. an exclude "foo" also accidentally excluding "foobar".
+    """
+    root_str = str(root)
+    return any(exclude.match(root_str) for exclude in excludes)