using an other version of generate_modules.py that structures the modules slightly better

git-svn-id: https://vsmartcard.svn.sourceforge.net/svnroot/vsmartcard@589 96b47cad-a561-4643-ad3b-153ac7d7599c

virtualsmartcard/doc/Makefile.am

@@ -2,7 +2,7 @@ EXTRA_DIST = README.rst generate_modules.py api
 
 .PHONY: doc
 doc:
-	./generate_modules.py $(top_srcdir)/src/vpicc --dest-dir=api --suffix=rst --no-toc
+	./generate_modules.py $(top_srcdir)/src/vpicc --dest-dir=api --suffix=rst --no-toc -1
 
 clean-local:
 	rm -rf api/*

virtualsmartcard/doc/generate_modules.py

@@ -8,6 +8,9 @@ creates ReST files appropriately to create code documentation with Sphinx.
 It also creates a modules index (named modules.<suffix>).
 """
 
+# This code was refactored by Robin Keller, rkeller@cars.com. The -1 option
+# was added to allow the script to only generate one module per file.
+
 # Copyright 2008 Société des arts technologiques (SAT), http://www.sat.qc.ca/
 # Copyright 2010 Thomas Waldmann <tw AT waldmann-edv DOT de>
 # All rights reserved.
@@ -33,7 +36,7 @@ import optparse
 # automodule options
 OPTIONS = ['members',
            'undoc-members',
-           # 'inherited-members', # disabled because there's a bug in sphinx
+           'inherited-members',
            'show-inheritance',
           ]
 
@@ -78,7 +81,8 @@ def format_directive(module, package=None):
 def create_module_file(package, module, opts):
     """Build the text of the file and write the file."""
     text = format_heading(1, '%s Module' % module)
-    text += format_heading(2, ':mod:`%s` Module' % module)
+    if not opts.onemodule:
+        text += format_heading(2, ':mod:`%s` Module' % module)
     text += format_directive(module, package)
     write_file(makename(package, module), text, opts)
 
@@ -87,28 +91,35 @@ def create_package_file(root, master_package, subroot, py_files, opts, subs):
     package = os.path.split(root)[-1]
     text = format_heading(1, '%s Package' % package)
     # add each package's module
-    for py_file in py_files:
+    if not opts.onemodule:
-        if shall_skip(os.path.join(root, py_file)):
+        for py_file in py_files:
-            continue
+            if shall_skip(os.path.join(root, py_file)):
-        is_package = py_file == INIT
+                continue
-        py_file = os.path.splitext(py_file)[0]
+            is_package = py_file == INIT
-        py_path = makename(subroot, py_file)
+            py_file = os.path.splitext(py_file)[0]
-        if is_package:
+            py_path = makename(subroot, py_file)
-            heading = ':mod:`%s` Package' % package
+            if is_package:
-        else:
+                heading = ':mod:`%s` Package' % package
-            heading = ':mod:`%s` Module' % py_file
+            else:
-        text += format_heading(2, heading)
+                heading = ':mod:`%s` Module' % py_file
-        text += format_directive(is_package and subroot or py_path, master_package)
+            text += format_heading(2, heading)
-        text += '\n'
+            text += format_directive(is_package and subroot or py_path, master_package)
+            text += '\n'
 
     # build a list of directories that are packages (they contain an INIT file)
     subs = [sub for sub in subs if os.path.isfile(os.path.join(root, sub, INIT))]
     # if there are some package directories, add a TOC for theses subpackages
-    if subs:
+    if subs or (opts.onemodule and py_files):
-        text += format_heading(2, 'Subpackages')
+        if not opts.onemodule:
+            text += format_heading(2, 'Subpackages')
         text += '.. toctree::\n\n'
         for sub in subs:
             text += '    %s.%s\n' % (makename(master_package, subroot), sub)
+        if opts.onemodule:
+            for py_file in py_files:
+                if py_file == INIT:
+                    continue
+                text += '    %s.%s\n' % (makename(master_package, subroot), py_file[:-3])
         text += '\n'
 
     write_file(makename(master_package, subroot), text, opts)
@@ -182,6 +193,14 @@ def recurse_tree(path, excludes, opts):
                ):
                 subroot = root[len(path):].lstrip(os.path.sep).replace(os.path.sep, '.')
                 create_package_file(root, package_name, subroot, py_files, opts, subs)
+                if opts.onemodule:
+                    for py_file in py_files:
+                        if py_file == INIT:
+                            continue
+                        if not shall_skip(os.path.join(root, py_file)):
+                            module = os.path.splitext(py_file)[0]
+                            create_module_file(makename(package_name, subroot), module, opts)
+                            toc.append(makename(package_name, module))
                 toc.append(makename(package_name, subroot))
         elif root == path:
             # if we are at the root level, we don't require it to be a package
@@ -241,6 +260,7 @@ Note: By default this script will not overwrite already created files.""")
     parser.add_option("-r", "--dry-run", action="store_true", dest="dryrun", help="Run the script without creating the files")
     parser.add_option("-f", "--force", action="store_true", dest="force", help="Overwrite all the files")
     parser.add_option("-t", "--no-toc", action="store_true", dest="notoc", help="Don't create the table of content file")
+    parser.add_option("-1", "--one-module", action="store_true", dest="onemodule", help="Store only one module per file")
     (opts, args) = parser.parse_args()
     if not args:
         parser.error("package path is required.")