diff options
Diffstat (limited to 'sphinx/apidoc.py')
| -rw-r--r-- | sphinx/apidoc.py | 31 |
1 files changed, 21 insertions, 10 deletions
diff --git a/sphinx/apidoc.py b/sphinx/apidoc.py index 755ea5ef..7b1a96d2 100644 --- a/sphinx/apidoc.py +++ b/sphinx/apidoc.py @@ -14,6 +14,8 @@ :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ +from __future__ import print_function + import os import sys import optparse @@ -53,12 +55,12 @@ def write_file(name, text, opts): """Write the output file for module/package <name>.""" fname = path.join(opts.destdir, '%s.%s' % (name, opts.suffix)) if opts.dryrun: - print 'Would create file %s.' % fname + print('Would create file %s.' % fname) return if not opts.force and path.isfile(fname): - print 'File %s already exists, skipping.' % fname + print('File %s already exists, skipping.' % fname) else: - print 'Creating file %s.' % fname + print('Creating file %s.' % fname) f = open(fname, 'w') try: f.write(text) @@ -86,7 +88,7 @@ def create_module_file(package, module, opts): text = format_heading(1, '%s module' % module) else: text = '' - #text += format_heading(2, ':mod:`%s` Module' % module) + # text += format_heading(2, ':mod:`%s` Module' % module) text += format_directive(module, package) write_file(makename(package, module), text, opts) @@ -95,6 +97,10 @@ def create_package_file(root, master_package, subroot, py_files, opts, subs): """Build the text of the file and write the file.""" text = format_heading(1, '%s package' % makename(master_package, subroot)) + if opts.modulefirst: + text += format_directive(subroot, master_package) + text += '\n' + # build a list of directories that are szvpackages (contain an INITPY file) subs = [sub for sub in subs if path.isfile(path.join(root, sub, INITPY))] # if there are some package directories, add a TOC for theses subpackages @@ -134,8 +140,9 @@ def create_package_file(root, master_package, subroot, py_files, opts, subs): text += '\n' text += '\n' - text += format_heading(2, 'Module contents') - text += format_directive(subroot, master_package) + if not opts.modulefirst: + text += format_heading(2, 'Module contents') + text += format_directive(subroot, master_package) write_file(makename(master_package, subroot), text, opts) @@ -166,7 +173,7 @@ def shall_skip(module, opts): # skip if it has a "private" name and this is selected filename = path.basename(module) if filename != '__init__.py' and filename.startswith('_') and \ - not opts.includeprivate: + not opts.includeprivate: return True return False @@ -211,7 +218,7 @@ def recurse_tree(rootpath, excludes, opts): if is_pkg: # we are in a package with something to document if subs or len(py_files) > 1 or not \ - shall_skip(path.join(root, INITPY), opts): + shall_skip(path.join(root, INITPY), opts): subpackage = root[len(rootpath):].lstrip(path.sep).\ replace(path.sep, '.') create_package_file(root, root_package, subpackage, @@ -287,6 +294,10 @@ Note: By default this script will not overwrite already created files.""") help='Don\'t create headings for the module/package ' 'packages (e.g. when the docstrings already contain ' 'them)') + parser.add_option('-M', '--module-first', action='store_true', + dest='modulefirst', + help='Put module documentation before submodule ' + 'documentation') parser.add_option('-s', '--suffix', action='store', dest='suffix', help='file suffix (default: rst)', default='rst') parser.add_option('-F', '--full', action='store_true', dest='full', @@ -307,7 +318,7 @@ Note: By default this script will not overwrite already created files.""") (opts, args) = parser.parse_args(argv[1:]) if opts.show_version: - print 'Sphinx (sphinx-apidoc) %s' % __version__ + print('Sphinx (sphinx-apidoc) %s' % __version__) return 0 if not args: @@ -321,7 +332,7 @@ Note: By default this script will not overwrite already created files.""") if opts.suffix.startswith('.'): opts.suffix = opts.suffix[1:] if not path.isdir(rootpath): - print >>sys.stderr, '%s is not a directory.' % rootpath + print('%s is not a directory.' % rootpath, file=sys.stderr) sys.exit(1) if not path.isdir(opts.destdir): if not opts.dryrun: |