tiledtmxloader3/doc/source/generate_modules.py

   1 #!/usr/bin/env python
   2 # -*- coding: utf-8 -*-
   3 """
   4 sphinx-autopackage-script
   5
   6 This script parses a directory tree looking for python modules and packages and
   7 creates ReST files appropriately to create code documentation with Sphinx.
   8 It also creates a modules index (named modules.<suffix>).
   9 """
  10
  11 # Copyright 2008 Société des arts technologiques (SAT), http://www.sat.qc.ca/
  12 # Copyright 2010 Thomas Waldmann <tw AT waldmann-edv DOT de>
  13 # All rights reserved.
  14 #
  15 # This program is free software: you can redistribute it and/or modify
  16 # it under the terms of the GNU General Public License as published by
  17 # the Free Software Foundation, either version 2 of the License, or
  18 # (at your option) any later version.
  19 #
  20 # This program is distributed in the hope that it will be useful,
  21 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  22 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  23 # GNU General Public License for more details.
  24 #
  25 # You should have received a copy of the GNU General Public License
  26 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  27
  28 # https://bitbucket.org/etienned/sphinx-autopackage-script/src/7199e9725789/generate_modules.py
  29 from __future__ import print_function
  30
  31 import os
  32 import optparse
  33
  34
  35 # automodule options
  36 OPTIONS = ['members',
  37            'undoc-members',
  38            # 'inherited-members', # disabled because there's a bug in sphinx
  39            'show-inheritance',
  40           ]
  41
  42 INIT = '__init__.py'
  43
  44 def makename(package, module):
  45     """Join package and module with a dot."""
  46     # Both package and module can be None/empty.
  47     if package:
  48         name = package
  49         if module:
  50             name += '.' + module
  51     else:
  52         name = module
  53     return name
  54
  55 def write_file(name, text, opts):
  56     """Write the output file for module/package <name>."""
  57     if opts.dryrun:
  58         return
  59     fname = os.path.join(opts.destdir, "%s.%s" % (name, opts.suffix))
  60     if not opts.force and os.path.isfile(fname):
  61         print('File %s already exists, skipping.' % fname)
  62     else:
  63         print('Creating file %s.' % fname)
  64         f = open(fname, 'w')
  65         f.write(text)
  66         f.close()
  67
  68 def format_heading(level, text):
  69     """Create a heading of <level> [1, 2 or 3 supported]."""
  70     underlining = ['=', '-', '~', ][level-1] * len(text)
  71     return '%s\n%s\n\n' % (text, underlining)
  72
  73 def format_directive(module, package=None):
  74     """Create the automodule directive and add the options."""
  75     directive = '.. automodule:: %s\n' % makename(package, module)
  76     for option in OPTIONS:
  77         directive += '    :%s:\n' % option
  78     return directive
  79
  80 def create_module_file(package, module, opts):
  81     """Build the text of the file and write the file."""
  82     text = format_heading(1, '%s Module' % module)
  83     text += format_heading(2, ':mod:`%s` Module' % module)
  84     text += format_directive(module, package)
  85     write_file(makename(package, module), text, opts)
  86
  87 def create_package_file(root, master_package, subroot, py_files, opts, subs):
  88     """Build the text of the file and write the file."""
  89     package = os.path.split(root)[-1]
  90     text = format_heading(1, '%s Package' % package)
  91     # add each package's module
  92     for py_file in py_files:
  93         if shall_skip(os.path.join(root, py_file)):
  94             continue
  95         is_package = py_file == INIT
  96         py_file = os.path.splitext(py_file)[0]
  97         py_path = makename(subroot, py_file)
  98         if is_package:
  99             heading = ':mod:`%s` Package' % package
 100         else:
 101             heading = ':mod:`%s` Module' % py_file
 102         text += format_heading(2, heading)
 103         text += format_directive(is_package and subroot or py_path, master_package)
 104         text += '\n'
 105
 106     # build a list of directories that are packages (they contain an INIT file)
 107     subs = [sub for sub in subs if os.path.isfile(os.path.join(root, sub, INIT))]
 108     # if there are some package directories, add a TOC for theses subpackages
 109     if subs:
 110         text += format_heading(2, 'Subpackages')
 111         text += '.. toctree::\n\n'
 112         for sub in subs:
 113             text += '    %s.%s\n' % (makename(master_package, subroot), sub)
 114         text += '\n'
 115
 116     write_file(makename(master_package, subroot), text, opts)
 117
 118 def create_modules_toc_file(master_package, modules, opts, name='index'):
 119     """
 120     Create the module's index.
 121     """
 122     text = format_heading(1, '%s Modules' % opts.header)
 123     text += '.. toctree::\n'
 124     text += '   :maxdepth: %s\n\n' % opts.maxdepth
 125
 126     modules.sort()
 127     prev_module = ''
 128     for module in modules:
 129         # look if the module is a subpackage and, if yes, ignore it
 130         if module.startswith(prev_module + '.'):
 131             continue
 132         prev_module = module
 133         text += '   %s\n' % module
 134
 135     write_file(name, text, opts)
 136
 137 def shall_skip(module):
 138     """
 139     Check if we want to skip this module.
 140     """
 141     # skip it, if there is nothing (or just \n or \r\n) in the file
 142     if os.path.getsize(module) < 3:
 143         return True
 144
 145     if module.find("setup.py") > -1 or module.find(os.sep + "dist" + os.sep) > -1:
 146         return True
 147
 148     return False
 149
 150 def recurse_tree(path, excludes, opts):
 151     """
 152     Look for every file in the directory tree and create the corresponding
 153     ReST files.
 154     """
 155     # use absolute path for root, as relative paths like '../../foo' cause
 156     # 'if "/." in root ...' to filter out *all* modules otherwise
 157     path = os.path.abspath(path)
 158     # check if the base directory is a package and get is name
 159     if INIT in os.listdir(path):
 160         package_name = path.split(os.path.sep)[-1]
 161     else:
 162         package_name = None
 163
 164     toc = []
 165     tree = os.walk(path, False)
 166     for root, subs, files in tree:
 167         # keep only the Python script files
 168         py_files =  sorted([f for f in files if os.path.splitext(f)[1] == '.py'])
 169         # exclude private modules, but not __init__.py files
 170         # py_files = sorted([f for f in py_files if not os.path.splitext(f)[0].startswith('_') or os.path.splitext(f)[0].startswith('__')])
 171         py_files = sorted([f for f in py_files if os.path.splitext(f)[0].find("_path.py") < 0])
 172         if INIT in py_files:
 173             py_files.remove(INIT)
 174             py_files.insert(0, INIT)
 175         # remove hidden ('.') and private ('_') directories
 176         subs = sorted([sub for sub in subs if sub[0] not in ['.', '_']])
 177         # check if there are valid files to process
 178         # TODO: could add check for windows hidden files
 179         if "/." in root or "/_" in root \
 180         or not py_files \
 181         or is_excluded(root, excludes):
 182             continue
 183         if INIT in py_files:
 184             # we are in package ...
 185             if (# ... with subpackage(s)
 186                 subs
 187                 or
 188                 # ... with some module(s)
 189                 len(py_files) > 1
 190                 or
 191                 # ... with a not-to-be-skipped INIT file
 192                 not shall_skip(os.path.join(root, INIT))
 193                ):
 194                 subroot = root[len(path):].lstrip(os.path.sep).replace(os.path.sep, '.')
 195                 create_package_file(root, package_name, subroot, py_files, opts, subs)
 196                 toc.append(makename(package_name, subroot))
 197         elif root == path:
 198             # if we are at the root level, we don't require it to be a package
 199             for py_file in py_files:
 200                 if not shall_skip(os.path.join(path, py_file)):
 201                     module = os.path.splitext(py_file)[0]
 202                     create_module_file(package_name, module, opts)
 203                     toc.append(makename(package_name, module))
 204
 205     # create the module's index
 206     if not opts.notoc:
 207         create_modules_toc_file(package_name, toc, opts)
 208
 209 def normalize_excludes(rootpath, excludes):
 210     """
 211     Normalize the excluded directory list:
 212     * must be either an absolute path or start with rootpath,
 213     * otherwise it is joined with rootpath
 214     * with trailing slash
 215     """
 216     sep = os.path.sep
 217     f_excludes = []
 218     for exclude in excludes:
 219         if not os.path.isabs(exclude) and not exclude.startswith(rootpath):
 220             exclude = os.path.join(rootpath, exclude)
 221         if not exclude.endswith(sep):
 222             exclude += sep
 223         f_excludes.append(exclude)
 224     return f_excludes
 225
 226 def is_excluded(root, excludes):
 227     """
 228     Check if the directory is in the exclude list.
 229
 230     Note: by having trailing slashes, we avoid common prefix issues, like
 231           e.g. an exlude "foo" also accidentally excluding "foobar".
 232     """
 233     sep = os.path.sep
 234     if not root.endswith(sep):
 235         root += sep
 236     for exclude in excludes:
 237         if root.startswith(exclude):
 238             return True
 239     return False
 240
 241 def main(args):
 242     """
 243     Parse and check the command line arguments.
 244     """
 245     parser = optparse.OptionParser(usage="""usage: %prog [options] <package path> [exclude paths, ...]
 246
 247 Note: By default this script will not overwrite already created files.""")
 248     parser.add_option("-n", "--doc-header", action="store", dest="header", help="Documentation Header (default=Project)", default="Project")
 249     parser.add_option("-d", "--dest-dir", action="store", dest="destdir", help="Output destination directory", default="")
 250     parser.add_option("-s", "--suffix", action="store", dest="suffix", help="module suffix (default=txt)", default="txt")
 251     parser.add_option("-m", "--maxdepth", action="store", dest="maxdepth", help="Maximum depth of submodules to show in the TOC (default=4)", type="int", default=4)
 252     parser.add_option("-r", "--dry-run", action="store_true", dest="dryrun", help="Run the script without creating the files")
 253     parser.add_option("-f", "--force", action="store_true", dest="force", help="Overwrite all the files")
 254     parser.add_option("-t", "--no-toc", action="store_true", dest="notoc", help="Don't create the table of content file")
 255     (opts, args) = parser.parse_args(args)
 256     if not args:
 257         parser.error("package path is required.")
 258     else:
 259         rootpath, excludes = args[0], args[1:]
 260         if os.path.isdir(rootpath):
 261             # check if the output destination is a valid directory
 262             if opts.destdir and os.path.isdir(opts.destdir):
 263                 excludes = normalize_excludes(rootpath, excludes)
 264                 recurse_tree(rootpath, excludes, opts)
 265             else:
 266                 print('%s is not a valid output destination directory.' % opts.destdir)
 267         else:
 268             print('%s is not a valid directory.' % rootpath)
 269
 270
 271 if __name__ == '__main__':
 272     import sys
 273     main(sys.argv[1:])
 274