From aaf8ca9e1b594776e009eec3062a0b3a31f546c7 Mon Sep 17 00:00:00 2001 From: Wes Turner Date: Sat, 19 Apr 2014 19:08:41 -0500 Subject: [PATCH] #1456: apidoc: Add a -M option to put module documentation before submodule documentation --- sphinx/apidoc.py | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/sphinx/apidoc.py b/sphinx/apidoc.py index 346956d31..487e2efe4 100644 --- a/sphinx/apidoc.py +++ b/sphinx/apidoc.py @@ -96,6 +96,9 @@ 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) + # 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 @@ -135,8 +138,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) @@ -288,6 +292,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',