diff options
Diffstat (limited to 'sphinx/ext/apidoc.py')
| -rw-r--r-- | sphinx/ext/apidoc.py | 93 |
1 files changed, 43 insertions, 50 deletions
diff --git a/sphinx/ext/apidoc.py b/sphinx/ext/apidoc.py index 591c640b8..94f07d91f 100644 --- a/sphinx/ext/apidoc.py +++ b/sphinx/ext/apidoc.py @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- """ sphinx.ext.apidoc ~~~~~~~~~~~~~~~~~ @@ -15,8 +14,6 @@ :license: BSD, see LICENSE for details. """ -from __future__ import print_function - import argparse import glob import locale @@ -25,14 +22,12 @@ import sys from fnmatch import fnmatch from os import path -from six import binary_type - import sphinx.locale from sphinx import __display_version__, package_dir from sphinx.cmd.quickstart import EXTENSIONS from sphinx.locale import __ from sphinx.util import rst -from sphinx.util.osutil import FileAvoidWrite, ensuredir, walk +from sphinx.util.osutil import FileAvoidWrite, ensuredir if False: # For type annotation @@ -54,7 +49,7 @@ PY_SUFFIXES = set(['.py', '.pyx']) def makename(package, module): - # type: (unicode, unicode) -> unicode + # type: (str, str) -> str """Join package and module with a dot.""" # Both package and module can be None/empty. if package: @@ -67,7 +62,7 @@ def makename(package, module): def write_file(name, text, opts): - # type: (unicode, unicode, Any) -> None + # type: (str, str, Any) -> None """Write the output file for module/package <name>.""" fname = path.join(opts.destdir, '%s.%s' % (name, opts.suffix)) if opts.dryrun: @@ -82,7 +77,7 @@ def write_file(name, text, opts): def format_heading(level, text, escape=True): - # type: (int, unicode, bool) -> unicode + # type: (int, str, bool) -> str """Create a heading of <level> [1, 2 or 3 supported].""" if escape: text = rst.escape(text) @@ -91,7 +86,7 @@ def format_heading(level, text, escape=True): def format_directive(module, package=None): - # type: (unicode, unicode) -> unicode + # type: (str, str) -> str """Create the automodule directive and add the options.""" directive = '.. automodule:: %s\n' % makename(package, module) for option in OPTIONS: @@ -100,7 +95,7 @@ def format_directive(module, package=None): def create_module_file(package, module, opts): - # type: (unicode, unicode, Any) -> None + # type: (str, str, Any) -> None """Build the text of the file and write the file.""" if not opts.noheadings: text = format_heading(1, '%s module' % module) @@ -112,7 +107,7 @@ def create_module_file(package, module, opts): def create_package_file(root, master_package, subroot, py_files, opts, subs, is_namespace, excludes=[]): # NOQA - # type: (unicode, unicode, unicode, List[unicode], Any, List[unicode], bool, List[unicode]) -> None # NOQA + # type: (str, str, str, List[str], Any, List[str], bool, List[str]) -> 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)) @@ -172,14 +167,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 + # type: (List[str], Any, str) -> None """Create the module's index.""" text = format_heading(1, '%s' % opts.header, escape=False) text += '.. toctree::\n' text += ' :maxdepth: %s\n\n' % opts.maxdepth modules.sort() - prev_module = '' # type: unicode + prev_module = '' for module in modules: # look if the module is a subpackage and, if yes, ignore it if module.startswith(prev_module + '.'): @@ -191,7 +186,7 @@ def create_modules_toc_file(modules, opts, name='modules'): def shall_skip(module, opts, excludes=[]): - # type: (unicode, Any, List[unicode]) -> bool + # type: (str, Any, List[str]) -> 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): @@ -218,7 +213,7 @@ def shall_skip(module, opts, excludes=[]): def recurse_tree(rootpath, excludes, opts): - # type: (unicode, List[unicode], Any) -> List[unicode] + # type: (str, List[str], Any) -> List[str] """ Look for every file in the directory tree and create the corresponding ReST files. @@ -235,7 +230,7 @@ def recurse_tree(rootpath, excludes, opts): root_package = None toplevels = [] - for root, subs, files in walk(rootpath, followlinks=followlinks): + for root, subs, files in os.walk(rootpath, followlinks=followlinks): # document only Python module files (that aren't excluded) py_files = sorted(f for f in files if path.splitext(f)[1] in PY_SUFFIXES and @@ -253,7 +248,7 @@ def recurse_tree(rootpath, excludes, opts): # remove hidden ('.') and private ('_') directories, as well as # excluded dirs if includeprivate: - exclude_prefixes = ('.',) # type: Tuple[unicode, ...] + exclude_prefixes = ('.',) # type: Tuple[str, ...] else: exclude_prefixes = ('.', '_') subs[:] = sorted(sub for sub in subs if not sub.startswith(exclude_prefixes) and @@ -283,7 +278,7 @@ def recurse_tree(rootpath, excludes, opts): def is_excluded(root, excludes): - # type: (unicode, List[unicode]) -> bool + # type: (str, List[str]) -> bool """Check if the directory is in the exclude list. Note: by having trailing slashes, we avoid common prefix issues, like @@ -376,6 +371,8 @@ Note: By default this script will not overwrite already created files.""")) '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')) for ext in EXTENSIONS: group.add_argument('--ext-%s' % ext, action='append_const', const='sphinx.ext.%s' % ext, dest='extensions', @@ -412,46 +409,42 @@ def main(argv=sys.argv[1:]): if args.full: from sphinx.cmd import quickstart as qs modules.sort() - prev_module = '' # type: unicode + prev_module = '' text = '' for module in modules: if module.startswith(prev_module + '.'): continue prev_module = module text += ' %s\n' % module - d = dict( - path = args.destdir, - sep = False, - dot = '_', - project = args.header, - author = args.author or 'Author', - version = args.version or '', - release = args.release or args.version or '', - suffix = '.' + args.suffix, - master = 'index', - epub = True, - extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', - 'sphinx.ext.todo'], - makefile = True, - batchfile = True, - make_mode = True, - mastertocmaxdepth = args.maxdepth, - mastertoctree = text, - language = 'en', - module_path = rootpath, - append_syspath = args.append_syspath, - ) + d = { + 'path': args.destdir, + 'sep': False, + 'dot': '_', + 'project': args.header, + 'author': args.author or 'Author', + 'version': args.version or '', + 'release': args.release or args.version or '', + 'suffix': '.' + args.suffix, + 'master': 'index', + 'epub': True, + 'extensions': ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', + 'sphinx.ext.todo'], + 'makefile': True, + 'batchfile': True, + 'make_mode': True, + 'mastertocmaxdepth': args.maxdepth, + 'mastertoctree': text, + 'language': 'en', + 'module_path': rootpath, + 'append_syspath': args.append_syspath, + } if args.extensions: d['extensions'].extend(args.extensions) - if isinstance(args.header, binary_type): - d['project'] = d['project'].decode('utf-8') - if isinstance(args.author, binary_type): - d['author'] = d['author'].decode('utf-8') - if isinstance(args.version, binary_type): - d['version'] = d['version'].decode('utf-8') - if isinstance(args.release, binary_type): - d['release'] = d['release'].decode('utf-8') + for ext in d['extensions'][:]: + if ',' in ext: + d['extensions'].remove(ext) + d['extensions'].extend(ext.split(',')) if not args.dryrun: qs.generate(d, silent=True, overwrite=args.force) |