forked from usgs/ps2ff
-
Notifications
You must be signed in to change notification settings - Fork 0
/
makedocs.py
executable file
·100 lines (82 loc) · 3.62 KB
/
makedocs.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
#!/usr/bin/env python
"""
Program to generate API docs from doc strings and put the results
into the docs directory.
"""
import argparse
import os.path
import sys
import tempfile
import pathlib
from distutils.dir_util import copy_tree
from impactutils.io.cmd import get_command_output
def main(args):
"""
Generate API docs.
Args:
args: Output of argparse. Currently only holds the verbose flag.
Returns:
Nothing. Function will exit upon success or failure.
"""
verbose = args.verbose
#-------------------------------------------------------------
# Some useful directories
#-------------------------------------------------------------
REPO_DIR = os.path.dirname(os.path.abspath(__file__))
DOCS_DIR = os.path.join(REPO_DIR, 'docs')
API_DIR = os.path.join(REPO_DIR, 'doc_source')
PACKAGE_DIR = os.path.join(REPO_DIR, 'ps2ff')
#-------------------------------------------------------------
# what is the package called and who are the authors
#-------------------------------------------------------------
PACKAGE = "ps2ff"
AUTHORS = 'Eric Thompson, Bruce Worden'
verstr = '1.1'
#-------------------------------------------------------------
# run the api doc command; this creates the .rst files
#-------------------------------------------------------------
sys.stderr.write('Building ps2ff API documentation (REST)...\n')
sphinx_cmd = 'sphinx-apidoc -o %s -f -e -l -M -d 12 -H %s -A "%s"'\
' -V %s %s' % (API_DIR, PACKAGE, AUTHORS, verstr,
PACKAGE_DIR)
res, stdout, stderr = get_command_output(sphinx_cmd)
if not res:
raise Exception('Could not build ps2ff API documentation'
' - error "%s".' % stderr)
if args.verbose:
print(stdout.decode('utf-8'))
print(stderr.decode('utf-8'))
#--------------------------------------------
# try to clean up some of the excess labeling
#--------------------------------------------
clean_cmd = "sed -i '' -e 's/ module//g' `find %s/*.rst -type f "\
"-maxdepth 0 -print`" % API_DIR
res, stdout, stderr = get_command_output(clean_cmd)
clean_cmd = "sed -i '' -e 's/ package//g' `find %s/*.rst -type f "\
"-maxdepth 0 -print`" % API_DIR
res, stdout, stderr = get_command_output(clean_cmd)
clean_cmd = "sed -i '' -e '/Subpackages/d' `find %s/*.rst -type f "\
"-maxdepth 0 -print`" % API_DIR
res, stdout, stderr = get_command_output(clean_cmd)
clean_cmd = "sed -i '' -e '/-.*-/d' `find %s/*.rst -type f "\
"-maxdepth 0 -print`" % API_DIR
res, stdout, stderr = get_command_output(clean_cmd)
#-------------------------------------------------------------
# Build the html
#-------------------------------------------------------------
sys.stderr.write('Building ps2ff pages (HTML)...\n')
res, stdout, stderr = get_command_output('sphinx-build -a -E doc_source docs')
if not res:
raise Exception('Could not build HTML for API documentation. - '
'error "%s"' % stderr.decode())
if args.verbose:
print(stdout.decode('utf-8'))
print(stderr.decode('utf-8'))
pathlib.Path(os.path.join(DOCS_DIR, '.nojekyll')).touch(exist_ok=True)
if __name__ == '__main__':
desc = 'Create API documentation for ps2ff.'
parser = argparse.ArgumentParser(description=desc)
parser.add_argument('-v', '--verbose', action='store_true', default=False,
help='Produce more output to the screen. ')
pargs = parser.parse_args()
main(pargs)