Mercurial > pylearn

annotate doc/scripts/docgen.py @ 908:9472d234db2e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
author fsavard
date Thu, 18 Mar 2010 11:33:49 -0400
parents
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