Debian Codegraph @

tools/ex2rst

raw ◀ ▶
1 Debian patch touch this file
•1 #!/usr/bin/env python3
2 #
3 # Note: this file is copied (possibly with minor modifications) from the
4 # sources of the PyMVPA project - http://pymvpa.org. It remains licensed as
5 # the rest of PyMVPA (MIT license as of October 2010).
6 #
7 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
8 #
9 # See COPYING file distributed along with the PyMVPA package for the
10 # copyright and license terms.
11 #
12 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
13
14 """Helper to automagically generate ReST versions of examples"""
15
16 __docformat__ = 'restructuredtext'
17
18
19 import os
20 import sys
21 import re
22 import glob
23 from optparse import OptionParser
24
25
26 def auto_image(line):
27 """Automatically replace generic image markers with ones that have full
28 size (width/height) info, plus a :target: link to the original png, to be
29 used in the html docs.
30 """
31 img_re = re.compile(r'(\s*)\.\. image::\s*(.*)$')
32 m = img_re.match(line)
33 if m is None:
34 # Not an image declaration, leave the line alone and return unmodified
35 return line
36
37 # Match means it's an image spec, we rewrite it with extra tags
38 ini_space = m.group(1)
39 lines = [line,
40 ini_space + ' :width: 500\n',
41 #ini_space + ' :height: 350\n'
42 ]
43 fspec = m.group(2)
44 if fspec.endswith('.*'):
45 fspec = fspec.replace('.*', '.png')
46 fspec = fspec.replace('fig/', '../_images/')
47 lines.append(ini_space + (' :target: %s\n' % fspec) )
48 lines.append('\n')
49 return ''.join(lines)
50
51 def exfile2rst(filename):
52 """Open a Python script and convert it into an ReST string.
53 """
54 # output string
55 s = ''
56
57 # open source file
58 xfile = open(filename)
59
60 # parser status vars
61 inheader = True
62 indocs = False
63 doc2code = False
64 code2doc = False
65 # an empty line found in the example enables the check for a potentially
66 # indented docstring starting on the next line (as an attempt to exclude
67 # function or class docstrings)
68 last_line_empty = False
69 # indentation of indented docstring, which is removed from the RsT output
70 # since we typically do not want an indentation there.
71 indent_level = 0
72
73 for line in xfile:
74 # skip header
75 if inheader and \
76 not (line.startswith('"""') or line.startswith("'''")):
77 continue
78 # determine end of header
79 if inheader and (line.startswith('"""') or line.startswith("'''")):
80 inheader = False
81
82 # strip comments and remove trailing whitespace
83 if not indocs and last_line_empty:
84 # first remove leading whitespace and store indent level
85 cleanline = line[:line.find('#')].lstrip()
86 indent_level = len(line) - len(cleanline) - 1
87 cleanline = cleanline.rstrip()
88 else:
89 cleanline = line[:line.find('#')].rstrip()
90
91 if not indocs and line == '\n':
92 last_line_empty = True
93 else:
94 last_line_empty = False
95
96 # if we have something that should go into the text
97 if indocs \
98 or (cleanline.startswith('"""') or cleanline.startswith("'''")):
99 proc_line = None
100 # handle doc start
101 if not indocs:
102 # guaranteed to start with """
103 if len(cleanline) > 3 \
104 and (cleanline.endswith('"""') \
105 or cleanline.endswith("'''")):
106 # single line doc
107 code2doc = True
108 doc2code = True
109 proc_line = cleanline[3:-3]
110 else:
111 # must be start of multiline block
112 indocs = True
113 code2doc = True
114 # rescue what is left on the line
115 proc_line = cleanline[3:] # strip """
116 else:
117 # we are already in the docs
118 # handle doc end
119 if cleanline.endswith('"""') or cleanline.endswith("'''"):
120 indocs = False
121 doc2code = True
122 # rescue what is left on the line
123 proc_line = cleanline[:-3]
124 # reset the indentation
125 indent_level = 0
126 else:
127 # has to be documentation
128 # if the indentation is whitespace remove it, other wise
129 # keep it (accounts for some variation in docstring
130 # styles
131 real_indent = \
132 indent_level - len(line[:indent_level].lstrip())
133 proc_line = line[real_indent:]
134
135 if code2doc:
136 code2doc = False
137 s += '\n'
138
139 proc_line = auto_image(proc_line)
140
141 if proc_line:
142 s += proc_line.rstrip() + '\n'
143
144 else:
145 if doc2code:
146 doc2code = False
147 s += '\n::\n'
148
149 # has to be code
150 s += ' %s' % line
151
152 xfile.close()
153
154 return s
155
156
157 def exfile2rstfile(filename, opts):
158 """
159 """
160 # doc filename
161 dfilename = os.path.basename(filename[:-3]) + '.rst'
162
163 # open dest file
164 dfile = open(os.path.join(opts.outdir, os.path.basename(dfilename)), 'w')
165
166 # place header
167 dfile.write('.. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n')
168
169 # place cross-ref target
170 dfile.write('.. _example_' + dfilename[:-4] + ':\n\n')
171
172 # write converted ReST
173 dfile.write(exfile2rst(filename))
174
175 if opts.sourceref:
176 # write post example see also box
177 msg = """
178
179 .. admonition:: Example source code
180
181 You can download :download:`the full source code of this example <%s>`.
182 This same script is also included in the %s source distribution under the
183 :file:`doc/examples/` directory.
184
185 """ % (filename, opts.project)
186
187 dfile.write(msg)
188
189 dfile.close()
190
191
192
193 def main():
194 parser = OptionParser( \
195 usage="%prog [options] <filename|directory> [...]", \
196 version="%prog 0.1", description="""\
197 %prog converts Python scripts into restructered text (ReST) format suitable for
198 integration into the Sphinx documentation framework. Its key feature is that it
199 extracts stand-alone (unassigned) single, or multiline triple-quote docstrings
200 and moves them out of the code listing so that they are rendered as regular
201 ReST, while at the same time maintaining their position relative to the
202 listing.
203
204 The detection of such docstrings is exclusively done by parsing the raw code so
205 it is never actually imported into a running Python session. Docstrings have to
206 be written using triple quotes (both forms " and ' are possible).
207
208 It is recommend that such docstrings are preceded and followed by an empty line.
209 Intended docstring can make use of the full linewidth from the second docstring
210 line on. If the indentation of multiline docstring is maintained for all lines,
211 the respective indentation is removed in the ReST output.
212
213 The parser algorithm automatically excludes file headers and starts with the
214 first (module-level) docstring instead.
215 """ ) #'
216
217 # define options
218 parser.add_option('--verbose', action='store_true', dest='verbose',
219 default=False, help='print status messages')
220 parser.add_option('-x', '--exclude', action='append', dest='excluded',
221 help="""\
222 Use this option to exclude single files from the to be parsed files. This is
223 especially useful to exclude files when parsing complete directories. This
224 option can be specified multiple times.
225 """)
226 parser.add_option('-o', '--outdir', action='store', dest='outdir',
227 type='string', default=None, help="""\
228 Target directory to write the ReST output to. This is a required option.
229 """)
230 parser.add_option('--no-sourceref', action='store_false', default=True,
231 dest='sourceref', help="""\
232 If specified, the source reference section will be suppressed.
233 """)
234 parser.add_option('--project', type='string', action='store', default='',
235 dest='project', help="""\
236 Name of the project that contains the examples. This name is used in the
237 'seealso' source references. Default: ''
238 """)
239
240 # parse options
241 (opts, args) = parser.parse_args() # read sys.argv[1:] by default
242
243 # check for required options
244 if opts.outdir is None:
245 print('Required option -o, --outdir not specified.')
246 sys.exit(1)
247
248 # build up list of things to parse
249 toparse = []
250 for t in args:
251 # expand dirs
252 if os.path.isdir(t):
253 # add all python files in that dir
254 toparse += glob.glob(os.path.join(t, '*.py'))
255 else:
256 toparse.append(t)
257
258 # filter parse list
259 if not opts.excluded is None:
260 toparse = [t for t in toparse if not t in opts.excluded]
261
262 toparse_list = toparse
263 toparse = set(toparse)
264
265 if len(toparse) != len(toparse_list):
266 print('Ignoring duplicate parse targets.')
267
268 if not os.path.exists(opts.outdir):
269 os.mkdir(outdir)
270
271 # finally process all examples
272 for t in toparse:
273 exfile2rstfile(t, opts)
274
275
276 if __name__ == '__main__':
277 main()