From cc570edf37a8e32d7c3323d59d225cae285570d4 Mon Sep 17 00:00:00 2001 From: dc mouser Date: Tue, 3 Sep 2013 15:52:56 -0500 Subject: [PATCH 1/2] Added option to apidoc to write each module to standalone page instead of combining all modules in a package on one page. --- sphinx/apidoc.py | 49 +++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 46 insertions(+), 3 deletions(-) diff --git a/sphinx/apidoc.py b/sphinx/apidoc.py index 500332c37..d622ad313 100644 --- a/sphinx/apidoc.py +++ b/sphinx/apidoc.py @@ -100,9 +100,42 @@ def create_package_file(root, master_package, subroot, py_files, opts, subs): heading = ':mod:`%s` Package' % package else: heading = ':mod:`%s` Module' % py_file - text += format_heading(2, heading) - text += format_directive(is_package and subroot or py_path, - master_package) + + + + # ATTN: mouser@donationcoder.com - 9/3/13 + # new option to have each module go on its own page + if (opts.separatepages): + if (is_package): + # we handle packages SLIGHTLY differently in this case; no need + # for double nested heading for package that apidoc usually does + # since all other modules are going to be on separate pages + text += format_directive(is_package and subroot or py_path, + master_package) + else: + # with separatepages option, instead of embedding all module + # file contents on the one package page, each module will have + # its own page. + outfilepath = py_path + '.singlepage' + # text for this page just links to standalone page + text += '.. toctree::\n\n' + text += ' %s\n\n' % outfilepath + # and now the contents of the standalone page file is just what + # apidoc used to write inside this page, but with top level + # heading. + filetext = format_heading(1, heading) + filetext += format_directive(is_package and subroot or py_path, + master_package) + # write out standalone page file + write_file(outfilepath, filetext, opts) + else: + # standard apidoc behavior + text += format_heading(2, heading) + text += format_directive(is_package and subroot or py_path, + master_package) + + + text += '\n' # build a list of directories that are packages (contain an INITPY file) @@ -272,6 +305,16 @@ Note: By default this script will not overwrite already created files.""") help='Project release, used when --full is given, ' 'defaults to --doc-version') + + + # ATTN: mouser@donationcoder.com - 9/3/13 + # Adding option to output each module on its own page rather than combine + # all modules in a package on one page. + parser.add_option('-E', '--separate-pages', action='store_true', dest='separatepages', + help='Put each module file in its own page, ') + + + (opts, args) = parser.parse_args(argv[1:]) if not args: From 3f888742ff1011e413dfa11d21819e3ae8bdf15d Mon Sep 17 00:00:00 2001 From: dc mouser Date: Sun, 8 Sep 2013 16:25:41 -0500 Subject: [PATCH 2/2] Added option to apidoc to have it output each module to its own page and updated apidoc docs. --- doc/man/sphinx-apidoc.rst | 1 + sphinx/apidoc.py | 15 ++------------- 2 files changed, 3 insertions(+), 13 deletions(-) diff --git a/doc/man/sphinx-apidoc.rst b/doc/man/sphinx-apidoc.rst index e48102deb..f00e29d87 100644 --- a/doc/man/sphinx-apidoc.rst +++ b/doc/man/sphinx-apidoc.rst @@ -33,6 +33,7 @@ Options -T, --no-toc Do not create a table of contents file. -F, --full If given, a full Sphinx project is generated (``conf.py``, ``Makefile`` etc.) using sphinx-quickstart. +-E, --separate Put each module file in its own page. These options are used with ``-F``: diff --git a/sphinx/apidoc.py b/sphinx/apidoc.py index d622ad313..9948b1cc2 100644 --- a/sphinx/apidoc.py +++ b/sphinx/apidoc.py @@ -101,10 +101,7 @@ def create_package_file(root, master_package, subroot, py_files, opts, subs): else: heading = ':mod:`%s` Module' % py_file - - - # ATTN: mouser@donationcoder.com - 9/3/13 - # new option to have each module go on its own page + # option to have each module go on its own page if (opts.separatepages): if (is_package): # we handle packages SLIGHTLY differently in this case; no need @@ -134,8 +131,6 @@ def create_package_file(root, master_package, subroot, py_files, opts, subs): text += format_directive(is_package and subroot or py_path, master_package) - - text += '\n' # build a list of directories that are packages (contain an INITPY file) @@ -304,13 +299,7 @@ Note: By default this script will not overwrite already created files.""") parser.add_option('-R', '--doc-release', action='store', dest='release', help='Project release, used when --full is given, ' 'defaults to --doc-version') - - - - # ATTN: mouser@donationcoder.com - 9/3/13 - # Adding option to output each module on its own page rather than combine - # all modules in a package on one page. - parser.add_option('-E', '--separate-pages', action='store_true', dest='separatepages', + parser.add_option('-E', '--separate', action='store_true', dest='separatepages', help='Put each module file in its own page, ')