Mercurial > pylearn

annotate doc/scripts/docgen.py @ 1018:790376d986a3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial document for sampling
author gdesjardins
date Fri, 03 Sep 2010 15:01:02 -0400
parents 9472d234db2e
children 57feab73c783
rev   line source
908
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
1 import sys
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
2 import os
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
3 import shutil
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
4 import inspect
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
5
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
6 from epydoc import docintrospecter
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
7 from epydoc.apidoc import RoutineDoc
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
8
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
9 import getopt
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
10 from collections import defaultdict
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
11
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
12 if __name__ == '__main__':
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
13
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
14 # make sure we're in the right directory
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
15 this_file_directory = os.path.abspath(os.path.dirname(__file__))
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
16 pylearn_root = os.path.join(os.path.join(this_file_directory, ".."), "..")
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
17
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
18 #pylearn_root = "/".join(sys.path[0].split("/")[:-2])
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
19
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
20 options = defaultdict(bool)
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
21 options.update(dict([x, y or True] for x, y in getopt.getopt(sys.argv[1:], 'o:', ['epydoc', 'rst', 'help', 'nopdf'])[0]))
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
22 if options['--help']:
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
23 print 'Usage: %s [OPTIONS]' % sys.argv[0]
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
24 print ' -o <dir>: output the html files in the specified dir'
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
25 print ' --rst: only compile the doc (requires sphinx)'
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
26 print ' --nopdf: do not produce a PDF file from the doc, only HTML'
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
27 print ' --epydoc: only compile the api documentation (requires epydoc)'
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
28 print ' --help: this help'
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
29 sys.exit(0)
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
30
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
31 options['--all'] = not (bool(options['--epydoc']) ^ bool(options['--rst']))
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
32
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
33 def mkdir(path):
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
34 try:
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
35 os.mkdir(path)
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
36 except OSError:
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
37 pass
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
38
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
39 outdir = options['-o'] or (pylearn_root + '/html')
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
40 mkdir(outdir)
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
41 os.chdir(outdir)
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
42 mkdir("doc")
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
43 mkdir("api")
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
44
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
45 # Make sure the appropriate 'theano' directory is in the PYTHONPATH
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
46 pythonpath = os.environ.get('PYTHONPATH', '')
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
47 pythonpath = pylearn_root + ':' + pythonpath
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
48 os.environ['PYTHONPATH'] = pythonpath
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
49
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
50 if options['--all'] or options['--epydoc']:
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
51 from epydoc.cli import cli
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
52 sys.path[0:0] = [pylearn_root]
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
53
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
54 #Generate HTML doc
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
55
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
56 ## This causes problems with the subsequent generation of sphinx doc
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
57 #sys.argv[:] = ['', '--config', '%s/doc/api/epydoc.conf' % pylearn_root, '-o', 'api']
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
58 #cli()
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
59 ## So we use this instead
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
60 os.system("epydoc --config %s/doc/api/epydoc.conf -o api" % pylearn_root)
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
61
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
62 # Generate PDF doc
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
63 # TODO
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
64
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
65 if options['--all'] or options['--rst']:
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
66 import sphinx
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
67 sys.path[0:0] = [os.path.join(pylearn_root, 'doc')]
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
68 sphinx.main(['', '-E', os.path.join(pylearn_root, 'doc'), '.'])
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
69
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
70 if not options['--nopdf']:
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
71 # Generate latex file in a temp directory
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
72 import tempfile
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
73 workdir = tempfile.mkdtemp()
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
74 sphinx.main(['', '-E', '-b', 'latex',
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
75 os.path.join(pylearn_root, 'doc'), workdir])
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
76 # Compile to PDF
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
77 os.chdir(workdir)
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
78 os.system('make')
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
79 try:
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
80 shutil.copy(os.path.join(workdir, 'pylearn.pdf'), outdir)
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
81 os.chdir(outdir)
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
82 shutil.rmtree(workdir)
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
83 except OSError, e:
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
84 print 'OSError:', e
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
85 except IOError, e:
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
86 print 'IOError:', e
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
87
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
88
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
89