1 | #!/usr/bin/env python |
---|
2 | """ |
---|
3 | Functions for building sphinx docs. |
---|
4 | |
---|
5 | For more information on the invocation of sphinx see: |
---|
6 | http://sphinx-doc.org/invocation.html |
---|
7 | """ |
---|
8 | import subprocess |
---|
9 | import os |
---|
10 | import sys |
---|
11 | import fnmatch |
---|
12 | import shutil |
---|
13 | import imp |
---|
14 | from glob import glob |
---|
15 | |
---|
16 | from distutils.dir_util import copy_tree |
---|
17 | from distutils.util import get_platform |
---|
18 | from shutil import copyfile |
---|
19 | |
---|
20 | platform = '.%s-%s'%(get_platform(),sys.version[:3]) |
---|
21 | |
---|
22 | CURRENT_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__)) |
---|
23 | |
---|
24 | run = imp.load_source('run', os.path.join(CURRENT_SCRIPT_DIR, '..', '..', 'run.py')) |
---|
25 | run.prepare() |
---|
26 | |
---|
27 | SASVIEW_SRC = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "src") |
---|
28 | SASVIEW_BUILD = os.path.abspath(os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "build", "lib"+platform)) |
---|
29 | SASVIEW_DOCS = os.path.join(SASVIEW_BUILD, "doc") |
---|
30 | SASVIEW_TEST = os.path.join(SASVIEW_SRC, "..", "sasview", "test", "media") |
---|
31 | |
---|
32 | # Need to slurp in the new sasmodels model definitions to replace the old model_functions.rst |
---|
33 | # We are currently here: |
---|
34 | #/sasview-local-trunk/docs/sphinx-docs/build_sphinx.py |
---|
35 | SASMODELS_SOURCE_MODELS = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", "sasmodels", "sasmodels", "models") |
---|
36 | SASMODELS_SOURCE_IMG = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", "sasmodels", "sasmodels", "models", "img") |
---|
37 | SASMODELS_DEST_MODELS = os.path.join(CURRENT_SCRIPT_DIR, "source", "user", "models") |
---|
38 | SASMODELS_DEST_IMG = os.path.join(CURRENT_SCRIPT_DIR, "source", "user", "models", "img") |
---|
39 | |
---|
40 | #print SASMODELS_SOURCE_MODELS |
---|
41 | #print SASMODELS_SOURCE_IMG |
---|
42 | #print SASMODELS_DEST_MODELS |
---|
43 | #print SASMODELS_DEST_IMG |
---|
44 | |
---|
45 | SPHINX_BUILD = os.path.join(CURRENT_SCRIPT_DIR, "build") |
---|
46 | SPHINX_SOURCE = os.path.join(CURRENT_SCRIPT_DIR, "source") |
---|
47 | SPHINX_SOURCE_API = os.path.join(SPHINX_SOURCE, "dev", "api") |
---|
48 | SPHINX_SOURCE_GUIFRAME = os.path.join(SPHINX_SOURCE, "user", "sasgui", "guiframe") |
---|
49 | SPHINX_SOURCE_MODELS = os.path.join(SPHINX_SOURCE, "user", "models") |
---|
50 | SPHINX_SOURCE_PERSPECTIVES = os.path.join(SPHINX_SOURCE, "user", "sasgui", "perspectives") |
---|
51 | SPHINX_SOURCE_TEST = os.path.join(SPHINX_SOURCE, "test") |
---|
52 | |
---|
53 | BUMPS_DOCS = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", |
---|
54 | "bumps", "doc", "guide") |
---|
55 | BUMPS_TARGET = os.path.join(SPHINX_SOURCE_PERSPECTIVES, "fitting") |
---|
56 | |
---|
57 | def _remove_dir(dir_path): |
---|
58 | """Removes the given directory.""" |
---|
59 | if os.path.isdir(dir_path): |
---|
60 | print "Removing \"%s\"... " % dir_path |
---|
61 | shutil.rmtree(dir_path) |
---|
62 | |
---|
63 | def clean(): |
---|
64 | """ |
---|
65 | Clean the sphinx build directory. |
---|
66 | """ |
---|
67 | print "=== Cleaning Sphinx Build ===" |
---|
68 | _remove_dir(SASVIEW_DOCS) |
---|
69 | _remove_dir(SPHINX_BUILD) |
---|
70 | _remove_dir(SPHINX_SOURCE_GUIFRAME) |
---|
71 | _remove_dir(SPHINX_SOURCE_MODELS) |
---|
72 | _remove_dir(SPHINX_SOURCE_PERSPECTIVES) |
---|
73 | _remove_dir(SPHINX_SOURCE_TEST) |
---|
74 | |
---|
75 | def retrieve_user_docs(): |
---|
76 | """ |
---|
77 | Copies across the contents of any media/ directories in src/, and puts them |
---|
78 | in an appropriately named directory of docs/sphinx-docs/source/. For |
---|
79 | example: |
---|
80 | |
---|
81 | sas/../[MODULE]/media/dir/A.rst |
---|
82 | sas/../[MODULE]/media/B.rst |
---|
83 | |
---|
84 | gets copied to a new location: |
---|
85 | |
---|
86 | docs/sphinx-docs/source/user/[MODULE]/dir/A.rst |
---|
87 | docs/sphinx-docs/source/user/[MODULE]/B.rst |
---|
88 | |
---|
89 | so that Sphinx may pick it up when generating the documentation. |
---|
90 | """ |
---|
91 | print "=== Retrieve User Docs ===" |
---|
92 | |
---|
93 | # Copy documentation files from their "source" to their "destination". |
---|
94 | for root, dirnames, _ in os.walk(SASVIEW_SRC): |
---|
95 | for dirname in fnmatch.filter(dirnames, 'media'): |
---|
96 | |
---|
97 | docs = os.path.abspath(os.path.join(root, dirname)) |
---|
98 | print "Found docs folder at \"%s\"." % docs |
---|
99 | |
---|
100 | dest_dir_part = os.path.dirname(os.path.relpath(docs, SASVIEW_SRC)) |
---|
101 | if os.sep in dest_dir_part: |
---|
102 | dest_dir_part = dest_dir_part[dest_dir_part.index(os.sep) + 1:] |
---|
103 | dest_dir = os.path.join(SPHINX_SOURCE, "user", dest_dir_part) |
---|
104 | |
---|
105 | copy_tree(docs, dest_dir) |
---|
106 | |
---|
107 | # Now pickup testdata_help.rst |
---|
108 | # print os.path.abspath(SASVIEW_TEST) |
---|
109 | # print os.path.abspath(SPHINX_SOURCE_TEST) |
---|
110 | if os.path.exists(SASVIEW_TEST): |
---|
111 | print "Found docs folder at ", SASVIEW_TEST |
---|
112 | shutil.copytree(SASVIEW_TEST, SPHINX_SOURCE_TEST) |
---|
113 | |
---|
114 | # Make sure we have the relevant images for the new sasmodels documentation |
---|
115 | copyfile(SASMODELS_SOURCE_IMG, SASMODELS_DEST_IMG) |
---|
116 | |
---|
117 | sys.exit() |
---|
118 | |
---|
119 | |
---|
120 | def retrieve_bumps_docs(): |
---|
121 | """ |
---|
122 | Copies select files from the bumps documentation into fitting perspective |
---|
123 | """ |
---|
124 | if os.path.exists(BUMPS_DOCS): |
---|
125 | print "=== Retrieve BUMPS Docs ===" |
---|
126 | filenames = [os.path.join(BUMPS_DOCS, "optimizer.rst")] |
---|
127 | filenames += glob(os.path.join(BUMPS_DOCS, "dream-*.png")) |
---|
128 | filenames += glob(os.path.join(BUMPS_DOCS, "fit-*.png")) |
---|
129 | for f in filenames: |
---|
130 | print "Copying file", f |
---|
131 | shutil.copy(f, BUMPS_TARGET) |
---|
132 | else: |
---|
133 | print """ |
---|
134 | *** Error *** missing directory %s |
---|
135 | The documentation will not include the optimizer selection section. |
---|
136 | Checkout the bumps source tree and rebuild the docs. |
---|
137 | |
---|
138 | |
---|
139 | """ % BUMPS_DOCS |
---|
140 | |
---|
141 | def apidoc(): |
---|
142 | """ |
---|
143 | Runs sphinx-apidoc to generate .rst files from the docstrings in .py files |
---|
144 | in the SasView build directory. |
---|
145 | """ |
---|
146 | print "=== Generate API Rest Files ===" |
---|
147 | |
---|
148 | # Clean directory before generating a new version. |
---|
149 | _remove_dir(SPHINX_SOURCE_API) |
---|
150 | |
---|
151 | subprocess.call(["sphinx-apidoc", |
---|
152 | "-o", SPHINX_SOURCE_API, # Output dir. |
---|
153 | "-d", "8", # Max depth of TOC. |
---|
154 | SASVIEW_BUILD]) |
---|
155 | |
---|
156 | def build(): |
---|
157 | """ |
---|
158 | Runs sphinx-build. Reads in all .rst files and spits out the final html. |
---|
159 | """ |
---|
160 | print "=== Build HTML Docs from Rest Files ===" |
---|
161 | subprocess.call(["sphinx-build", |
---|
162 | "-b", "html", # Builder name. TODO: accept as arg to setup.py. |
---|
163 | "-d", os.path.join(SPHINX_BUILD, "doctrees"), |
---|
164 | SPHINX_SOURCE, |
---|
165 | os.path.join(SPHINX_BUILD, "html")]) |
---|
166 | |
---|
167 | print "=== Copy HTML Docs to Build Directory ===" |
---|
168 | html = os.path.join(SPHINX_BUILD, "html") |
---|
169 | copy_tree(html, SASVIEW_DOCS) |
---|
170 | |
---|
171 | def rebuild(): |
---|
172 | clean() |
---|
173 | retrieve_user_docs() |
---|
174 | retrieve_bumps_docs() |
---|
175 | apidoc() |
---|
176 | build() |
---|
177 | |
---|
178 | print "=== Done ===" |
---|
179 | |
---|
180 | if __name__ == "__main__": |
---|
181 | rebuild() |
---|