| •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() |