#!/usr/bin/env python
"""
summarize.py
Show a summary about which Numpy functions are documented and which are not.
"""
import os, glob, re, sys, inspect, optparse
sys.path.append(os.path.join(os.path.dirname(__file__), 'sphinxext'))
from sphinxext.phantom_import import import_phantom_module
from sphinxext.autosummary_generate import get_documented
CUR_DIR = os.path.dirname(__file__)
SOURCE_DIR = os.path.join(CUR_DIR, 'source', 'reference')
SKIP_LIST = """
# --- aliases:
alltrue sometrue bitwise_not cumproduct
row_stack column_stack product rank
# -- skipped:
core lib f2py dual doc emath ma rec char distutils oldnumeric numarray
testing version matlib
add_docstring add_newdoc add_newdocs fastCopyAndTranspose pkgload
conjugate disp
int0 object0 unicode0 uint0 string_ string0 void0
flagsobj
setup setupscons PackageLoader
lib.scimath.arccos lib.scimath.arcsin lib.scimath.arccosh lib.scimath.arcsinh
lib.scimath.arctanh lib.scimath.log lib.scimath.log2 lib.scimath.log10
lib.scimath.logn lib.scimath.power lib.scimath.sqrt
# --- numpy.random:
random random.info random.mtrand random.ranf random.sample random.random
# --- numpy.fft:
fft fft.Tester fft.bench fft.fftpack fft.fftpack_lite fft.helper
fft.refft fft.refft2 fft.refftn fft.irefft fft.irefft2 fft.irefftn
fft.info fft.test
# --- numpy.linalg:
linalg linalg.Tester
linalg.bench linalg.info linalg.lapack_lite linalg.linalg linalg.test
# --- numpy.ctypeslib:
ctypeslib ctypeslib.test
""".split()
def main():
p = optparse.OptionParser(__doc__)
p.add_option("-c", "--columns", action="store", type="int", dest="cols",
default=3, help="Maximum number of columns")
options, args = p.parse_args()
if len(args) != 0:
p.error('Wrong number of arguments')
# prepare
fn = os.path.join(CUR_DIR, 'dump.xml')
if os.path.isfile(fn):
import_phantom_module(fn)
# check
documented, undocumented = check_numpy()
# report
in_sections = {}
for name, locations in documented.iteritems():
for (filename, section, keyword, toctree) in locations:
in_sections.setdefault((filename, section, keyword), []).append(name)
print "Documented"
print "==========\n"
last_filename = None
for (filename, section, keyword), names in sorted(in_sections.items()):
if filename != last_filename:
print "--- %s\n" % filename
last_filename = filename
print " ** ", section
print format_in_columns(sorted(names), options.cols)
print "\n"
print ""
print "Undocumented"
print "============\n"
print format_in_columns(sorted(undocumented.keys()), options.cols)
def check_numpy():
documented = get_documented(glob.glob(SOURCE_DIR + '/*.rst'))
undocumented = {}
import numpy, numpy.fft, numpy.linalg, numpy.random
for mod in [numpy, numpy.fft, numpy.linalg, numpy.random,
numpy.ctypeslib, numpy.emath, numpy.ma]:
undocumented.update(get_undocumented(documented, mod, skip=SKIP_LIST))
for d in (documented, undocumented):
for k in d.keys():
if k.startswith('numpy.'):
d[k[6:]] = d[k]
del d[k]
return documented, undocumented
def get_undocumented(documented, module, module_name=None, skip=[]):
"""
Find out which items in Numpy are not documented.
Returns
-------
undocumented : dict of bool
Dictionary containing True for each documented item name
and False for each undocumented one.
"""
undocumented = {}
if module_name is None:
module_name = module.__name__
for name in dir(module):
obj = getattr(module, name)
if name.startswith('_'): continue
full_name = '.'.join([module_name, name])
if full_name in skip: continue
if full_name.startswith('numpy.') and full_name[6:] in skip: continue
if not (inspect.ismodule(obj) or callable(obj) or inspect.isclass(obj)):
continue
if full_name not in documented:
undocumented[full_name] = True
return undocumented
def format_in_columns(lst, max_columns):
"""
Format a list containing strings to a string containing the items
in columns.
"""
lst = map(str, lst)
col_len = max(map(len, lst)) + 2
ncols = 80//col_len
if ncols > max_columns:
ncols = max_columns
if ncols <= 0:
ncols = 1
if len(lst) % ncols == 0:
nrows = len(lst)//ncols
else:
nrows = 1 + len(lst)//ncols
fmt = ' %%-%ds ' % (col_len-2)
lines = []
for n in range(nrows):
lines.append("".join([fmt % x for x in lst[n::nrows]]))
return "\n".join(lines)
if __name__ == "__main__": main()
|