Mercurial > pylearn

annotate doc/scripts/docgen.py @ 1516:57feab73c783

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Remove :api: role, do not generate epydoc by default
author Pascal Lamblin <lamblinp@iro.umontreal.ca>
date Mon, 05 Mar 2012 17:35:15 -0500
parents 9472d234db2e
children
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
1516
57feab73c783 Remove :api: role, do not generate epydoc by default
Pascal Lamblin <lamblinp@iro.umontreal.ca>
parents: 908
diff changeset
31 if not (options['--epydoc'] or options['--rst']):
57feab73c783 Remove :api: role, do not generate epydoc by default
Pascal Lamblin <lamblinp@iro.umontreal.ca>
parents: 908
diff changeset
32 # Default is now rst
57feab73c783 Remove :api: role, do not generate epydoc by default
Pascal Lamblin <lamblinp@iro.umontreal.ca>
parents: 908
diff changeset
33 options['--rst'] = True
908
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
34
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
35 def mkdir(path):
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
36 try:
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
37 os.mkdir(path)
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
38 except OSError:
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
39 pass
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
40
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
41 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
42 mkdir(outdir)
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
43 os.chdir(outdir)
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']:
1516
57feab73c783 Remove :api: role, do not generate epydoc by default
Pascal Lamblin <lamblinp@iro.umontreal.ca>
parents: 908
diff changeset
51 mkdir("api")
908
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
52 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
53 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
54
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
55 #Generate HTML doc
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
56
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
57 ## 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
58 #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
59 #cli()
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
60 ## 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
61 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
62
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
63 # Generate PDF doc
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
64 # TODO
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
65
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
66 if options['--all'] or options['--rst']:
1516
57feab73c783 Remove :api: role, do not generate epydoc by default
Pascal Lamblin <lamblinp@iro.umontreal.ca>
parents: 908
diff changeset
67 mkdir("doc")
908
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
68 import sphinx
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
69 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
70 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
71
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
72 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
73 # 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
74 import tempfile
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
75 workdir = tempfile.mkdtemp()
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
76 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
77 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
78 # Compile to PDF
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
79 os.chdir(workdir)
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
80 os.system('make')
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
81 try:
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
82 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
83 os.chdir(outdir)
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
84 shutil.rmtree(workdir)
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
85 except OSError, e:
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
86 print 'OSError:', e
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
87 except IOError, e:
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
88 print 'IOError:', e
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
89
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
90
9472d234db2e Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory
fsavard
parents:
diff changeset
91