mirror of
https://github.com/OpenFOAM/ThirdParty-6.git
synced 2025-12-08 06:57:43 +00:00
445 lines
17 KiB
Python
445 lines
17 KiB
Python
# -*- coding: utf-8 -*-
|
|
"""
|
|
sphinx.apidoc **modified**
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
This is a modified version of apidoc.py provided by Sphinx. We have modified
|
|
it to generate separate rst files for each of modules in ParaView e.g.
|
|
paraview.simple, paraview.servermanager etc. The default behavior is that
|
|
all these modules are documented on the same page corresponding to the
|
|
package which is very hard to read, especially in case of ParaView.
|
|
|
|
Following is the original header form the file.
|
|
~~~~~~~~~~~~~
|
|
|
|
sphinx.apidoc
|
|
|
|
Parses a directory tree looking for Python modules and packages and creates
|
|
ReST files appropriately to create code documentation with Sphinx. It also
|
|
creates a modules index (named modules.<suffix>).
|
|
|
|
This is derived from the "sphinx-autopackage" script, which is:
|
|
Copyright 2008 Société des arts technologiques (SAT),
|
|
http://www.sat.qc.ca/
|
|
|
|
:copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
|
|
:license: BSD, see LICENSE for details.
|
|
"""
|
|
import os
|
|
import sys
|
|
import optparse
|
|
from os import path
|
|
|
|
# Custom module filter for ParaView
|
|
def is_exclude_module(module):
|
|
excludeList = ['paraview/vtk/vtk','paraview/vtk/tk','paraview/vtk/gtk','paraview/vtk/test', 'paraview/vtk/qt', 'paraview/vtk/wx', 'paraview/vtk/util', 'paraview/_arg', 'paraview/compile_all', 'paraview/vtkConstants']
|
|
m = str(module)
|
|
for exclude in excludeList:
|
|
if m.__contains__(exclude):
|
|
print "Exclude:", m
|
|
return True
|
|
return False
|
|
|
|
# automodule options
|
|
if 'SPHINX_APIDOC_OPTIONS' in os.environ:
|
|
OPTIONS = os.environ['SPHINX_APIDOC_OPTIONS'].split(',')
|
|
else:
|
|
OPTIONS = [
|
|
'members',
|
|
'undoc-members',
|
|
# 'inherited-members', # disabled because there's a bug in sphinx
|
|
'show-inheritance',
|
|
]
|
|
|
|
INITPY = '__init__.py'
|
|
|
|
|
|
def makename(package, module):
|
|
"""Join package and module with a dot."""
|
|
# Both package and module can be None/empty.
|
|
if package:
|
|
name = package
|
|
if module:
|
|
name += '.' + module
|
|
else:
|
|
name = module
|
|
return name
|
|
|
|
|
|
def write_file(name, text, opts):
|
|
"""Write the output file for module/package <name>."""
|
|
fname = path.join(opts.destdir, '%s.%s' % (name, opts.suffix))
|
|
if opts.dryrun:
|
|
print 'Would create file %s.' % fname
|
|
return
|
|
if not opts.force and path.isfile(fname):
|
|
print 'File %s already exists, skipping.' % fname
|
|
else:
|
|
print 'Creating file %s.' % fname
|
|
f = open(fname, 'w')
|
|
try:
|
|
f.write(text)
|
|
finally:
|
|
f.close()
|
|
|
|
|
|
def format_heading(level, text):
|
|
"""Create a heading of <level> [1, 2 or 3 supported]."""
|
|
underlining = ['=', '-', '~', ][level-1] * len(text)
|
|
return '%s\n%s\n\n' % (text, underlining)
|
|
|
|
|
|
def format_directive(module, package=None):
|
|
"""Create the automodule directive and add the options."""
|
|
directive = '.. automodule:: %s\n' % makename(package, module)
|
|
for option in OPTIONS:
|
|
directive += ' :%s:\n' % option
|
|
return directive
|
|
|
|
def format_simple_directive(module, proxy_list, package=None, main_module=True):
|
|
"""Create the automodule directive for the simple module."""
|
|
if main_module:
|
|
directive = '.. automodule:: %s\n' % makename(package, module)
|
|
directive += ' :members:\n'
|
|
directive += ' :exclude-members: %s\n' % ','.join(proxy_list)
|
|
for option in OPTIONS:
|
|
if option != 'members':
|
|
directive += ' :%s:\n' % option
|
|
else:
|
|
directive = '.. currentmodule:: %s\n\n' %makename(package, module)
|
|
# Adding a hidden toctree to prevent warnings about document not
|
|
# included in any toc.
|
|
# This is also required instead of :toctree: argument of autosummary
|
|
# directive to prevent a clobbered top level index file.
|
|
directive += '.. toctree::\n'
|
|
directive += ' :hidden:\n\n'
|
|
for prx in proxy_list:
|
|
directive += ' %s.%s.%s\n' % (package, module, prx)
|
|
directive += '\n.. autosummary::\n'
|
|
directive += ' :nosignatures:\n\n'
|
|
for prx in proxy_list:
|
|
directive += ' %s\n' % prx
|
|
return directive
|
|
|
|
def format_simple_proxy_directive(prx, package='paraview', module='simple'):
|
|
"""Create the autoclass directive for proxy"""
|
|
directive = '.. currentmodule:: %s.%s\n\n' % (package, module)
|
|
directive += '.. autofunction:: %s\n\n' % prx
|
|
|
|
# Parse pydoc output for the proxy
|
|
import parse_pydoc_output
|
|
parser = parse_pydoc_output.ParsePyDocOutput('%s.%s' %(package, module),
|
|
['servermanager'], prx)
|
|
directive += format_heading(2, 'Data Descriptors')
|
|
directive += '%s\n\n' % parser.data_mems.replace('*', '\\*')
|
|
inh_data_mems = parser.inh_data_mems
|
|
for inh_data_mem in inh_data_mems:
|
|
directive += format_heading(3, 'Data Descriptors inherited from %s'\
|
|
% inh_data_mem)
|
|
directive += '%s\n\n' % inh_data_mems[inh_data_mem].replace('*', '\\*')
|
|
directive += format_heading(2, 'Methods')
|
|
directive += '%s\n\n' % parser.method_mems.replace('*', '\\*')
|
|
inh_method_mems = parser.inh_method_mems
|
|
for inh_method_mem in inh_method_mems:
|
|
directive += format_heading(3, 'Methods inherited from %s'\
|
|
% inh_method_mem)
|
|
directive += '%s\n\n' % inh_method_mems[inh_method_mem].replace('*', '\\*')
|
|
return directive
|
|
|
|
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)
|
|
text += format_directive(module, package)
|
|
write_file(makename(package, module), text, opts)
|
|
|
|
def create_simple_module_files(package, module, proxy, opts):
|
|
"""Build the text of the simple and proxy files and write them."""
|
|
import paraview.simple
|
|
gen_prx = sorted(paraview.simple._get_generated_proxies())
|
|
|
|
# Create file for simple module
|
|
text = format_heading(1, '%s Module' % module)
|
|
text += "For generated server-side proxies, please refer to "\
|
|
":doc:`paraview.servermanager_proxies`\n\n"
|
|
text += format_simple_directive(module, gen_prx, package)
|
|
write_file(makename(package, module), text, opts)
|
|
|
|
# Create a common summary page for all generated proxies
|
|
text = format_heading(1, 'Available readers, sources, writers, filters and animation cues')
|
|
text += "Proxies generated for server side objects "\
|
|
"under :doc:`paraview.simple`\n\n"
|
|
text += format_simple_directive(module, gen_prx, package, False)
|
|
write_file(makename(package, proxy), text, opts)
|
|
|
|
# Create a separate file for each proxy
|
|
for prx in gen_prx:
|
|
text = format_heading(1, '%s.%s.%s' % (package, module, prx))
|
|
text += format_simple_proxy_directive(prx)
|
|
text += '\n\nFor the full list of servermanager proxies, please refer to '\
|
|
':doc:`Available readers, sources, writers, filters and animation cues <paraview.servermanager_proxies>`'
|
|
write_file(makename('%s.%s' % (package, module), prx), text, opts)
|
|
|
|
def create_package_file(root, master_package, subroot, py_files, opts, subs):
|
|
"""Build the text of the file and write the file."""
|
|
# **modified**
|
|
# This function has been modified from the original. We now create a
|
|
# separate file for each module in the package, rather than adding it to the
|
|
# same file.
|
|
package = path.split(root)[-1]
|
|
text = format_heading(1, '%s Package' % package)
|
|
|
|
modules = []
|
|
# add each module in the package
|
|
for py_file in py_files:
|
|
if shall_skip(path.join(root, py_file)):
|
|
continue
|
|
is_package = py_file == INITPY
|
|
py_file = path.splitext(py_file)[0]
|
|
py_path = makename(subroot, py_file)
|
|
if is_package:
|
|
heading = ':mod:`%s` Package' % package
|
|
text += format_heading(2, heading)
|
|
text += format_directive(is_package and subroot or py_path,
|
|
master_package)
|
|
text += '\n'
|
|
else:
|
|
if master_package == 'paraview' and py_path == 'simple':
|
|
proxy_path = 'servermanager_proxies'
|
|
create_simple_module_files(master_package, py_path, proxy_path,
|
|
opts)
|
|
modules.append(makename(master_package, py_path))
|
|
modules.append(makename(master_package, proxy_path))
|
|
else:
|
|
# create a new file for the module.
|
|
create_module_file(master_package, py_path, opts)
|
|
modules.append(makename(master_package, py_path))
|
|
|
|
if modules:
|
|
text += format_heading(2, 'Modules')
|
|
text += '.. toctree::\n\n'
|
|
for module in modules:
|
|
text += ' %s\n' % module
|
|
text += '\n'
|
|
|
|
# build a list of directories that are packages (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
|
|
if subs:
|
|
text += format_heading(2, 'Subpackages')
|
|
text += '.. toctree::\n\n'
|
|
for sub in subs:
|
|
text += ' %s.%s\n' % (makename(master_package, subroot), sub)
|
|
text += '\n'
|
|
|
|
write_file(makename(master_package, subroot), text, opts)
|
|
|
|
|
|
def create_modules_toc_file(modules, opts, name='modules'):
|
|
"""Create the module's index."""
|
|
text = format_heading(1, '%s' % opts.header)
|
|
text += '.. toctree::\n'
|
|
text += ' :maxdepth: %s\n\n' % opts.maxdepth
|
|
|
|
modules.sort()
|
|
prev_module = ''
|
|
for module in modules:
|
|
# look if the module is a subpackage and, if yes, ignore it
|
|
if module.startswith(prev_module + '.'):
|
|
continue
|
|
prev_module = module
|
|
text += ' %s\n' % module
|
|
|
|
write_file(name, text, opts)
|
|
|
|
|
|
def shall_skip(module):
|
|
"""Check if we want to skip this module."""
|
|
# skip it if there is nothing (or just \n or \r\n) in the file
|
|
if is_exclude_module(module):
|
|
return True
|
|
|
|
return path.getsize(module) <= 2
|
|
|
|
|
|
def recurse_tree(rootpath, excludes, opts):
|
|
"""
|
|
Look for every file in the directory tree and create the corresponding
|
|
ReST files.
|
|
"""
|
|
# use absolute path for root, as relative paths like '../../foo' cause
|
|
# 'if "/." in root ...' to filter out *all* modules otherwise
|
|
rootpath = path.normpath(path.abspath(rootpath))
|
|
# check if the base directory is a package and get its name
|
|
if INITPY in os.listdir(rootpath):
|
|
root_package = rootpath.split(path.sep)[-1]
|
|
else:
|
|
# otherwise, the base is a directory with packages
|
|
root_package = None
|
|
|
|
toplevels = []
|
|
for root, subs, files in os.walk(rootpath):
|
|
if is_excluded(root, excludes):
|
|
del subs[:]
|
|
continue
|
|
# document only Python module files
|
|
py_files = sorted([f for f in files if path.splitext(f)[1] == '.py'])
|
|
is_pkg = INITPY in py_files
|
|
if is_pkg:
|
|
py_files.remove(INITPY)
|
|
py_files.insert(0, INITPY)
|
|
elif root != rootpath:
|
|
# only accept non-package at toplevel
|
|
del subs[:]
|
|
continue
|
|
# remove hidden ('.') and private ('_') directories
|
|
subs[:] = sorted(sub for sub in subs if sub[0] not in ['.', '_'])
|
|
|
|
if is_pkg:
|
|
# we are in a package with something to document
|
|
if subs or len(py_files) > 1 or not \
|
|
shall_skip(path.join(root, INITPY)):
|
|
subpackage = root[len(rootpath):].lstrip(path.sep).\
|
|
replace(path.sep, '.')
|
|
create_package_file(root, root_package, subpackage,
|
|
py_files, opts, subs)
|
|
toplevels.append(makename(root_package, subpackage))
|
|
else:
|
|
# if we are at the root level, we don't require it to be a package
|
|
assert root == rootpath and root_package is None
|
|
for py_file in py_files:
|
|
if not shall_skip(path.join(rootpath, py_file)):
|
|
module = path.splitext(py_file)[0]
|
|
create_module_file(root_package, module, opts)
|
|
toplevels.append(module)
|
|
|
|
return toplevels
|
|
|
|
|
|
def normalize_excludes(rootpath, excludes):
|
|
"""
|
|
Normalize the excluded directory list:
|
|
* must be either an absolute path or start with rootpath,
|
|
* otherwise it is joined with rootpath
|
|
* with trailing slash
|
|
"""
|
|
f_excludes = []
|
|
for exclude in excludes:
|
|
if not path.isabs(exclude) and not exclude.startswith(rootpath):
|
|
exclude = path.join(rootpath, exclude)
|
|
f_excludes.append(path.normpath(exclude) + path.sep)
|
|
return f_excludes
|
|
|
|
|
|
def is_excluded(root, excludes):
|
|
"""
|
|
Check if the directory is in the exclude list.
|
|
|
|
Note: by having trailing slashes, we avoid common prefix issues, like
|
|
e.g. an exlude "foo" also accidentally excluding "foobar".
|
|
"""
|
|
sep = path.sep
|
|
if not root.endswith(sep):
|
|
root += sep
|
|
for exclude in excludes:
|
|
if root.startswith(exclude):
|
|
return True
|
|
return False
|
|
|
|
|
|
def main(argv=sys.argv):
|
|
"""
|
|
Parse and check the command line arguments.
|
|
"""
|
|
parser = optparse.OptionParser(
|
|
usage="""\
|
|
usage: %prog [options] -o <output_path> <module_path> [exclude_paths, ...]
|
|
|
|
Look recursively in <module_path> for Python modules and packages and create
|
|
one reST file with automodule directives per package in the <output_path>.
|
|
|
|
Note: By default this script will not overwrite already created files.""")
|
|
|
|
parser.add_option('-o', '--output-dir', action='store', dest='destdir',
|
|
help='Directory to place all output', default='')
|
|
parser.add_option('-d', '--maxdepth', action='store', dest='maxdepth',
|
|
help='Maximum depth of submodules to show in the TOC '
|
|
'(default: 2)', type='int', default=2)
|
|
parser.add_option('-f', '--force', action='store_true', dest='force',
|
|
help='Overwrite all files')
|
|
parser.add_option('-n', '--dry-run', action='store_true', dest='dryrun',
|
|
help='Run the script without creating files')
|
|
parser.add_option('-T', '--no-toc', action='store_true', dest='notoc',
|
|
help='Don\'t create a table of contents file')
|
|
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',
|
|
help='Generate a full project with sphinx-quickstart')
|
|
parser.add_option('-H', '--doc-project', action='store', dest='header',
|
|
help='Project name (default: root module name)')
|
|
parser.add_option('-A', '--doc-author', action='store', dest='author',
|
|
type='str',
|
|
help='Project author(s), used when --full is given')
|
|
parser.add_option('-V', '--doc-version', action='store', dest='version',
|
|
help='Project version, used when --full is given')
|
|
parser.add_option('-R', '--doc-release', action='store', dest='release',
|
|
help='Project release, used when --full is given, '
|
|
'defaults to --doc-version')
|
|
|
|
(opts, args) = parser.parse_args(argv[1:])
|
|
|
|
if not args:
|
|
parser.error('A package path is required.')
|
|
|
|
rootpath, excludes = args[0], args[1:]
|
|
if not opts.destdir:
|
|
parser.error('An output directory is required.')
|
|
if opts.header is None:
|
|
opts.header = path.normpath(rootpath).split(path.sep)[-1]
|
|
if opts.suffix.startswith('.'):
|
|
opts.suffix = opts.suffix[1:]
|
|
if not path.isdir(rootpath):
|
|
print >>sys.stderr, '%s is not a directory.' % rootpath
|
|
sys.exit(1)
|
|
if not path.isdir(opts.destdir):
|
|
if not opts.dryrun:
|
|
os.makedirs(opts.destdir)
|
|
excludes = normalize_excludes(rootpath, excludes)
|
|
modules = recurse_tree(rootpath, excludes, opts)
|
|
print "Detected Packages:\n\t", "\n\t".join(modules)
|
|
if opts.full:
|
|
from sphinx import quickstart as qs
|
|
modules.sort()
|
|
prev_module = ''
|
|
text = ''
|
|
for module in modules:
|
|
if module.startswith(prev_module + '.'):
|
|
continue
|
|
prev_module = module
|
|
text += ' %s\n' % module
|
|
d = dict(
|
|
path = opts.destdir,
|
|
sep = False,
|
|
dot = '_',
|
|
project = opts.header,
|
|
author = opts.author or 'Author',
|
|
version = opts.version or '',
|
|
release = opts.release or opts.version or '',
|
|
suffix = '.' + opts.suffix,
|
|
master = 'index',
|
|
epub = True,
|
|
ext_autodoc = True,
|
|
ext_viewcode = True,
|
|
makefile = True,
|
|
batchfile = True,
|
|
mastertocmaxdepth = opts.maxdepth,
|
|
mastertoctree = text,
|
|
)
|
|
if not opts.dryrun:
|
|
qs.generate(d, silent=True, overwrite=opts.force)
|
|
elif not opts.notoc:
|
|
create_modules_toc_file(modules, opts)
|
|
|
|
if __name__ == "__main__":
|
|
main()
|