diff options
Diffstat (limited to 'sphinx/apidoc.py')
| -rw-r--r-- | sphinx/apidoc.py | 24 |
1 files changed, 20 insertions, 4 deletions
diff --git a/sphinx/apidoc.py b/sphinx/apidoc.py index 19a711370..0fca17d81 100644 --- a/sphinx/apidoc.py +++ b/sphinx/apidoc.py @@ -26,6 +26,10 @@ from fnmatch import fnmatch from sphinx.util.osutil import FileAvoidWrite, walk from sphinx import __display_version__ +if False: + # For type annotation + from typing import Any, Tuple # NOQA + # automodule options if 'SPHINX_APIDOC_OPTIONS' in os.environ: OPTIONS = os.environ['SPHINX_APIDOC_OPTIONS'].split(',') @@ -42,6 +46,7 @@ PY_SUFFIXES = set(['.py', '.pyx']) def makename(package, module): + # type: (unicode, unicode) -> unicode """Join package and module with a dot.""" # Both package and module can be None/empty. if package: @@ -54,6 +59,7 @@ def makename(package, module): def write_file(name, text, opts): + # type: (unicode, unicode, Any) -> None """Write the output file for module/package <name>.""" fname = path.join(opts.destdir, '%s.%s' % (name, opts.suffix)) if opts.dryrun: @@ -68,12 +74,14 @@ def write_file(name, text, opts): def format_heading(level, text): + # type: (int, unicode) -> unicode """Create a heading of <level> [1, 2 or 3 supported].""" underlining = ['=', '-', '~', ][level - 1] * len(text) return '%s\n%s\n\n' % (text, underlining) def format_directive(module, package=None): + # type: (unicode, unicode) -> unicode """Create the automodule directive and add the options.""" directive = '.. automodule:: %s\n' % makename(package, module) for option in OPTIONS: @@ -82,6 +90,7 @@ def format_directive(module, package=None): def create_module_file(package, module, opts): + # type: (unicode, unicode, Any) -> None """Build the text of the file and write the file.""" if not opts.noheadings: text = format_heading(1, '%s module' % module) @@ -93,6 +102,7 @@ def create_module_file(package, module, opts): def create_package_file(root, master_package, subroot, py_files, opts, subs, is_namespace): + # type: (unicode, unicode, unicode, List[unicode], Any, List[unicode], bool) -> None """Build the text of the file and write the file.""" text = format_heading(1, ('%s package' if not is_namespace else "%s namespace") % makename(master_package, subroot)) @@ -148,13 +158,14 @@ def create_package_file(root, master_package, subroot, py_files, opts, subs, is_ def create_modules_toc_file(modules, opts, name='modules'): + # type: (List[unicode], Any, unicode) -> None """Create the module's index.""" text = format_heading(1, '%s' % opts.header) text += '.. toctree::\n' text += ' :maxdepth: %s\n\n' % opts.maxdepth modules.sort() - prev_module = '' + prev_module = '' # type: unicode for module in modules: # look if the module is a subpackage and, if yes, ignore it if module.startswith(prev_module + '.'): @@ -166,6 +177,7 @@ def create_modules_toc_file(modules, opts, name='modules'): def shall_skip(module, opts): + # type: (unicode, Any) -> bool """Check if we want to skip this module.""" # skip if the file doesn't exist and not using implicit namespaces if not opts.implicit_namespaces and not path.exists(module): @@ -184,6 +196,7 @@ def shall_skip(module, opts): def recurse_tree(rootpath, excludes, opts): + # type: (unicode, List[unicode], Any) -> List[unicode] """ Look for every file in the directory tree and create the corresponding ReST files. @@ -217,7 +230,7 @@ def recurse_tree(rootpath, excludes, opts): # remove hidden ('.') and private ('_') directories, as well as # excluded dirs if includeprivate: - exclude_prefixes = ('.',) + exclude_prefixes = ('.',) # type: Tuple[unicode, ...] else: exclude_prefixes = ('.', '_') subs[:] = sorted(sub for sub in subs if not sub.startswith(exclude_prefixes) and @@ -247,23 +260,26 @@ def recurse_tree(rootpath, excludes, opts): def normalize_excludes(rootpath, excludes): + # type: (unicode, List[unicode]) -> List[unicode] """Normalize the excluded directory list.""" return [path.abspath(exclude) for exclude in excludes] def is_excluded(root, excludes): + # type: (unicode, List[unicode]) -> bool """Check if the directory is in the exclude list. Note: by having trailing slashes, we avoid common prefix issues, like e.g. an exlude "foo" also accidentally excluding "foobar". """ for exclude in excludes: - if fnmatch(root, exclude): + if fnmatch(root, exclude): # type: ignore return True return False def main(argv=sys.argv): + # type: (List[str]) -> int """Parse and check the command line arguments.""" parser = optparse.OptionParser( usage="""\ @@ -359,7 +375,7 @@ Note: By default this script will not overwrite already created files.""") if opts.full: from sphinx import quickstart as qs modules.sort() - prev_module = '' + prev_module = '' # type: unicode text = '' for module in modules: if module.startswith(prev_module + '.'): |