Georg Brandl avatar Georg Brandl committed 471c8e3 Merge

Merged in dcmouser/sphinx-fork-dcmouser (pull request #161)

Added option to apidoc to write each module to standalone page instead of combining all modules in a package on one page.

Comments (0)

Files changed (2)

doc/man/sphinx-apidoc.rst

 -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``:
 
             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)
+
+        # 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)
     parser.add_option('-R', '--doc-release', action='store', dest='release',
                       help='Project release, used when --full is given, '
                       'defaults to --doc-version')
+    parser.add_option('-E', '--separate', action='store_true', dest='separatepages',
+                      help='Put each module file in its own page, ')
+
+
 
     (opts, args) = parser.parse_args(argv[1:])
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.