18
18
import argparse
19
19
from contextlib import contextmanager
20
20
import jinja2
21
+ import webbrowser
21
22
22
23
23
24
DOC_PATH = os .path .dirname (os .path .abspath (__file__ ))
26
27
BUILD_DIRS = ['doctrees' , 'html' , 'latex' , 'plots' , '_static' , '_templates' ]
27
28
28
29
29
- def _generate_index (include_api , single_doc = None ):
30
+ def _generate_index (include_api = True , single_doc = None ):
30
31
"""Create index.rst file with the specified sections.
31
32
32
33
Parameters
@@ -48,6 +49,36 @@ def _generate_index(include_api, single_doc=None):
48
49
single_doc = single_doc ))
49
50
50
51
52
+ def _generate_exclude_pattern (include_api = True , single_doc = None ):
53
+
54
+ if not include_api :
55
+ rst_files = ['api.rst' , 'generated/*.rst' ]
56
+ elif single_doc is not None :
57
+ rst_files = [f for f in os .listdir (SOURCE_PATH )
58
+ if ((f .endswith ('.rst' ) or f .endswith ('.ipynb' ))
59
+ and (f != 'index.rst' ) and (f != single_doc ))]
60
+ rst_files += ['generated/*.rst' ]
61
+ else :
62
+ rst_files = []
63
+
64
+ exclude_patterns = "," .join (['{!r}' .format (i ) for i in ['**.ipynb_checkpoints' ] + rst_files ])
65
+
66
+ return exclude_patterns
67
+
68
+
69
+ def _write_temp_file (classtype , module , function ):
70
+
71
+ s = """{1}.{2}
72
+ =================================
73
+
74
+ .. currentmodule:: {1}
75
+
76
+ .. auto{0}:: {2}""" .format (classtype , module , function )
77
+
78
+ with open (os .path .join (SOURCE_PATH , "temp.rst" ), 'w' ) as f :
79
+ f .write (s )
80
+
81
+
51
82
@contextmanager
52
83
def _maybe_exclude_notebooks ():
53
84
"""Skip building the notebooks if pandoc is not installed.
@@ -96,8 +127,9 @@ class DocBuilder:
96
127
All public methods of this class can be called as parameters of the
97
128
script.
98
129
"""
99
- def __init__ (self , num_jobs = 1 ):
130
+ def __init__ (self , num_jobs = 1 , exclude_patterns = None ):
100
131
self .num_jobs = num_jobs
132
+ self .exclude_patterns = exclude_patterns
101
133
102
134
@staticmethod
103
135
def _create_build_structure ():
@@ -142,8 +174,8 @@ def _sphinx_build(self, kind):
142
174
self ._run_os ('sphinx-build' ,
143
175
'-j{}' .format (self .num_jobs ),
144
176
'-b{}' .format (kind ),
145
- '-d{}' .format (os .path .join (BUILD_PATH ,
146
- 'doctrees' )),
177
+ '-d{}' .format (os .path .join (BUILD_PATH , 'doctrees' )),
178
+ # TODO integrate exclude_patterns
147
179
SOURCE_PATH ,
148
180
os .path .join (BUILD_PATH , kind ))
149
181
@@ -199,6 +231,23 @@ def zip_html(self):
199
231
'-q' ,
200
232
* fnames )
201
233
234
+ def build_docstring (self ):
235
+ """Build single docstring page"""
236
+ self ._create_build_structure ()
237
+
238
+ args = ('sphinx-build' ,
239
+ '-bhtml' ,
240
+ '-d{}' .format (os .path .join (BUILD_PATH , 'doctrees' )),
241
+ '-Dexclude_patterns={}' .format (self .exclude_patterns ),
242
+ SOURCE_PATH ,
243
+ os .path .join (BUILD_PATH , 'html' ),
244
+ os .path .join (SOURCE_PATH , 'temp.rst' )
245
+ )
246
+ # for some reason it does not work with run_os, but it does if I
247
+ # directly call the joined command
248
+ # self._run_os(*args)
249
+ os .system (" " .join (args ))
250
+
202
251
203
252
def main ():
204
253
cmds = [method for method in dir (DocBuilder ) if not method .startswith ('_' )]
@@ -228,15 +277,34 @@ def main():
228
277
type = str ,
229
278
default = os .path .join (DOC_PATH , '..' ),
230
279
help = 'path' )
280
+ argparser .add_argument ('--docstring' ,
281
+ metavar = 'FILENAME' ,
282
+ type = str ,
283
+ default = None ,
284
+ help = ('method or function name to compile, '
285
+ 'e.g. "DataFrame.join"' ))
231
286
args = argparser .parse_args ()
232
287
233
288
if args .command not in cmds :
234
289
raise ValueError ('Unknown command {}. Available options: {}' .format (
235
290
args .command , ', ' .join (cmds )))
236
291
237
292
os .environ ['PYTHONPATH' ] = args .python_path
238
- _generate_index (not args .no_api , args .single )
239
- getattr (DocBuilder (args .num_jobs ), args .command )()
293
+
294
+ if args .docstring is not None :
295
+ _write_temp_file ('method' , 'pandas' , args .docstring )
296
+ exclude_patterns = _generate_exclude_pattern (single_doc = 'temp.rst' )
297
+ _generate_index (single_doc = 'temp.rst' )
298
+ DocBuilder (args .num_jobs , exclude_patterns ).build_docstring ()
299
+ url = "file://" + os .getcwd () + "/build/html/temp.html"
300
+ webbrowser .open (url , new = 2 )
301
+ os .remove ('source/temp.rst' )
302
+
303
+ else :
304
+ _generate_index (not args .no_api , args .single )
305
+ exclude_patterns = _generate_exclude_pattern (
306
+ not args .no_api , args .single )
307
+ getattr (DocBuilder (args .num_jobs , exclude_patterns ), args .command )()
240
308
241
309
242
310
if __name__ == '__main__' :
0 commit comments