-
Notifications
You must be signed in to change notification settings - Fork 106
/
make_docs.py
executable file
·210 lines (175 loc) · 7.7 KB
/
make_docs.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
"""
This script builds the python documentation from the function signature and the
customized markdown files. The processed documentation is saved as ascii text
files which are loaded on runtime and replace the __doc__ string of the f2py
wrapped functions.
"""
from __future__ import absolute_import as _absolute_import
from __future__ import division as _division
from __future__ import print_function as _print_function
import sys
import os
import re
import textwrap
import _SHTOOLS
import _constant
def main():
# ---- input/output folders ----
docfolder = os.path.abspath(sys.argv[1])
libfolder = os.path.abspath(sys.argv[2])
mddocfolder = os.path.join(docfolder, 'src', 'pydoc')
pydocfolder = os.path.join(libfolder, 'pyshtools', 'doc')
print('-- searching documentation in folder: {} --'.format(mddocfolder))
# ---- loop through the f2py _SHTOOLS functions and make docstrings ----
for name, func in _SHTOOLS.__dict__.items():
if callable(func):
try:
# ---- process and load documentation ----
# ---- read md file documentation: ----
fname_mddoc = os.path.join(mddocfolder, 'py' +
name.lower() + '.md')
if (os.path.isfile(fname_mddoc)):
docstring = process_mddoc(fname_mddoc)
# ---- save combined docstring in the pydoc folder ----
fname_pydoc = os.path.join(pydocfolder, name.lower() +
'.doc')
with open(fname_pydoc, 'w') as pydocfile:
pydocfile.write(docstring)
except IOError as msg:
print(msg)
# ---- loop through functions that are defined in python ----
pyfunctions = ['PlmIndex', 'YilmIndexVector']
for name in pyfunctions:
try:
# ---- process and load documentation
# read md file documentation:
fname_mddoc = os.path.join(mddocfolder, 'py' + name.lower() +
'.md')
docstring = process_mddoc(fname_mddoc)
# ---- save combined docstring in the pydoc folder--
fname_pydoc = os.path.join(pydocfolder, name.lower() + '.doc')
with open(fname_pydoc, 'w') as pydocfile:
pydocfile.write(docstring)
except IOError as msg:
print(msg)
# ---- loop through the f2py constants and make docstrings ----
for name, value in _constant.planetsconstants.__dict__.items():
try:
# ---- read md file documentation:
fname_mddoc = os.path.join(mddocfolder, 'constant_' +
name.lower() + '.md')
docstring = process_mddoc(fname_mddoc)
# ---- save docstring in the pydoc folder----
fname_pydoc = os.path.join(pydocfolder, 'constant_' +
name.lower() + '.doc')
with open(fname_pydoc, 'w') as pydocfile:
pydocfile.write(docstring)
except IOError as msg:
print(msg)
# ===== PROCESS MD DOCUMENTATION FILE ====
def process_mddoc(fname_mddoc):
# ---- md file search patterns ----
revalue = re.compile('## Value\n\n', re.DOTALL)
retail = re.compile('# See (.*)', re.DOTALL)
reh2 = re.compile('## (.*?)\n', re.DOTALL)
reh1 = re.compile('\A# (.*?)\n', re.DOTALL)
reh1b = re.compile('\n# (.*?)\n', re.DOTALL)
recode = re.compile('`(.*?)`', re.DOTALL)
restaresc = re.compile(r'(\\\*)', re.DOTALL)
# rebold = re.compile('(?![\])[*](.*?)(?![\])[*]',re.DOTALL)
# ---- open md file and search for patterns ----
with open(fname_mddoc, 'r') as mdfile:
# remove the first two lines
mdstring = mdfile.read().split('\n', 2)[2]
# First, remove '## Value\n\n' from constant documentation
match = revalue.search(mdstring)
if match is not None:
mdstring = re.sub(match.group(0), '', mdstring)
match = retail.search(mdstring)
if match is not None:
mdstring = mdstring.replace(match.group(0), '')
match = reh1.search(mdstring)
while match is not None:
mdstring = re.sub(match.group(0), match.group(1) + '\n' +
len(match.group(1)) * '-', mdstring)
match = reh1.search(mdstring)
match = reh1b.search(mdstring)
while match is not None:
mdstring = re.sub(match.group(0), '\n' + match.group(1) + '\n' +
len(match.group(1)) * '-', mdstring)
match = reh1b.search(mdstring)
match = reh2.search(mdstring)
while match is not None:
mdstring = re.sub(match.group(0), match.group(1) + '\n' +
len(match.group(1)) * '-', mdstring)
match = reh2.search(mdstring)
match = recode.search(mdstring)
while match is not None:
mdstring = mdstring.replace(match.group(0), match.group(1))
match = recode.search(mdstring)
match = restaresc.search(mdstring)
while match is not None:
mdstring = mdstring.replace(match.group(0), '*')
match = recode.search(mdstring)
# ---- combine into docstring ----
docstring = ''
tmp = mdstring.splitlines(True)
# --- remove line breaks between parameters ---
for i in range(0, len(tmp)-3):
if tmp[i][0:4] == ': ' and tmp[i+3][0:4] == ': ':
tmp[i+1] = ''
for i in range(0, len(tmp)):
if tmp[i][0:4] == ': ':
docstring += textwrap.fill(tmp[i][4:], width=80,
replace_whitespace=False,
initial_indent=' ',
subsequent_indent=' ') + '\n'
elif tmp[i] == '':
pass
else:
docstring += textwrap.fill(tmp[i], width=80,
replace_whitespace=False) + '\n'
return docstring
# ===== PROCESS F2PY DOCUMENTATION ====
def process_f2pydoc(f2pydoc):
"""
this function replace all optional _d0 arguments with their default values
in the function signature. These arguments are not intended to be used and
signify merely the array dimensions of the associated argument.
"""
# ---- split f2py document in its parts
# 0=Call Signature
# 1=Parameters
# 2=Other (optional) Parameters (only if present)
# 3=Returns
docparts = re.split('\n--', f2pydoc)
if len(docparts) == 4:
doc_has_optionals = True
elif len(docparts) == 3:
doc_has_optionals = False
else:
print('-- uninterpretable f2py documentation --')
return f2pydoc
# ---- replace arguments with _d suffix with empty string in ----
# ---- function signature (remove them): ----
docparts[0] = re.sub('[\[(,]\w+_d\d', '', docparts[0])
# ---- replace _d arguments of the return arrays with their default value:
if doc_has_optionals:
returnarray_dims = re.findall('[\[(,](\w+_d\d)', docparts[3])
for arg in returnarray_dims:
searchpattern = arg + ' : input.*\n.*Default: (.*)\n'
match = re.search(searchpattern, docparts[2])
if match:
default = match.group(1)
docparts[3] = re.sub(arg, default, docparts[3])
docparts[2] = re.sub(searchpattern, '', docparts[2])
# ---- remove all optional _d# from optional argument list:
if doc_has_optionals:
searchpattern = '\w+_d\d : input.*\n.*Default: (.*)\n'
docparts[2] = re.sub(searchpattern, '', docparts[2])
# ---- combine doc parts to a single string
processed_signature = '\n--'.join(docparts)
return processed_signature
# ==== EXECUTE SCRIPT ====
if __name__ == "__main__":
main()