[9bf64f6] | 1 | #!/usr/bin/env python |
---|
[35bf493] | 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 |
---|
[296f290] | 13 | import imp |
---|
[c22c5e3] | 14 | from glob import glob |
---|
[35bf493] | 15 | |
---|
| 16 | from distutils.dir_util import copy_tree |
---|
| 17 | from distutils.util import get_platform |
---|
[d2143ab] | 18 | from shutil import copy |
---|
[b7a2ebfd] | 19 | from os import listdir |
---|
[35bf493] | 20 | |
---|
| 21 | platform = '.%s-%s'%(get_platform(),sys.version[:3]) |
---|
| 22 | |
---|
| 23 | CURRENT_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__)) |
---|
| 24 | |
---|
[296f290] | 25 | run = imp.load_source('run', os.path.join(CURRENT_SCRIPT_DIR, '..', '..', 'run.py')) |
---|
| 26 | run.prepare() |
---|
| 27 | |
---|
[35bf493] | 28 | SASVIEW_SRC = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "src") |
---|
| 29 | SASVIEW_BUILD = os.path.abspath(os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "build", "lib"+platform)) |
---|
| 30 | SASVIEW_DOCS = os.path.join(SASVIEW_BUILD, "doc") |
---|
[2fb09c4] | 31 | SASVIEW_TEST = os.path.join(SASVIEW_SRC, "..", "sasview", "test", "media") |
---|
[35bf493] | 32 | |
---|
[5802e7b] | 33 | # Need to slurp in the new sasmodels model definitions to replace the old model_functions.rst |
---|
| 34 | # We are currently here: |
---|
| 35 | #/sasview-local-trunk/docs/sphinx-docs/build_sphinx.py |
---|
[a728658] | 36 | SASMODELS_SOURCE_PROLOG = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", "sasmodels", "doc") |
---|
[18a1f2b] | 37 | SASMODELS_SOURCE_MAGNETISM = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", "sasmodels", "doc", "ref", "magnetism") |
---|
[bb0c836] | 38 | SASMODELS_SOURCE_REF_MODELS = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", "sasmodels", "doc", "ref", "models") |
---|
[354524d] | 39 | SASMODELS_SOURCE_MODELS = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", "sasmodels", "doc", "model") |
---|
| 40 | SASMODELS_SOURCE_IMG = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", "sasmodels", "doc", "model", "img") |
---|
[5420ef6] | 41 | SASMODELS_SOURCE_AUTOIMG = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", "sasmodels", "doc", "_build", "html","_images") |
---|
[a728658] | 42 | SASMODELS_DEST_PROLOG = os.path.join(CURRENT_SCRIPT_DIR, "source") |
---|
| 43 | SASMODELS_DEST_REF_MODELS = os.path.join(CURRENT_SCRIPT_DIR, "source", "user") |
---|
[756e8ce] | 44 | SASMODELS_DEST_MODELS = os.path.join(CURRENT_SCRIPT_DIR, "source", "user", "models") |
---|
[f603bec] | 45 | SASMODELS_DEST_IMG = os.path.join(CURRENT_SCRIPT_DIR, "source", "user", "model-imgs", "new-models") |
---|
[5420ef6] | 46 | SASMODELS_DEST_BUILDIMG = os.path.join(CURRENT_SCRIPT_DIR, "source", "user", "models", "img") |
---|
[5802e7b] | 47 | |
---|
[a728658] | 48 | #if os.path.exists(SASMODELS_SOURCE_PROLOG): |
---|
| 49 | # print "Found models prolog folder at ", SASMODELS_SOURCE_PROLOG |
---|
| 50 | #if os.path.exists(SASMODELS_SOURCE_REF_MODELS): |
---|
| 51 | # print "Found models ref folder at ", SASMODELS_SOURCE_REF_MODELS |
---|
[b7a2ebfd] | 52 | #if os.path.exists(SASMODELS_SOURCE_MODELS): |
---|
| 53 | # print "Found models folder at ", SASMODELS_SOURCE_MODELS |
---|
| 54 | #if os.path.exists(SASMODELS_SOURCE_IMG): |
---|
| 55 | # print "Found img folder at ", SASMODELS_SOURCE_IMG |
---|
[a728658] | 56 | #if os.path.exists(SASMODELS_DEST_REF_MODELS): |
---|
| 57 | # print "Found models ref folder at ", SASMODELS_DEST_REF_MODELS |
---|
[b7a2ebfd] | 58 | #if os.path.exists(SASMODELS_DEST_MODELS): |
---|
| 59 | # print "Found models folder at ", SASMODELS_DEST_MODELS |
---|
| 60 | #if os.path.exists(SASMODELS_DEST_IMG): |
---|
| 61 | # print "Found img folder at ", SASMODELS_DEST_IMG |
---|
[a728658] | 62 | #sys.exit() |
---|
[5802e7b] | 63 | |
---|
[35bf493] | 64 | SPHINX_BUILD = os.path.join(CURRENT_SCRIPT_DIR, "build") |
---|
| 65 | SPHINX_SOURCE = os.path.join(CURRENT_SCRIPT_DIR, "source") |
---|
| 66 | SPHINX_SOURCE_API = os.path.join(SPHINX_SOURCE, "dev", "api") |
---|
[ba31ed1] | 67 | SPHINX_SOURCE_GUIFRAME = os.path.join(SPHINX_SOURCE, "user", "sasgui", "guiframe") |
---|
[7168b8b] | 68 | SPHINX_SOURCE_MODELS = os.path.join(SPHINX_SOURCE, "user", "models") |
---|
[ba31ed1] | 69 | SPHINX_SOURCE_PERSPECTIVES = os.path.join(SPHINX_SOURCE, "user", "sasgui", "perspectives") |
---|
[2fb09c4] | 70 | SPHINX_SOURCE_TEST = os.path.join(SPHINX_SOURCE, "test") |
---|
[35bf493] | 71 | |
---|
[c22c5e3] | 72 | BUMPS_DOCS = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", |
---|
| 73 | "bumps", "doc", "guide") |
---|
| 74 | BUMPS_TARGET = os.path.join(SPHINX_SOURCE_PERSPECTIVES, "fitting") |
---|
| 75 | |
---|
[bb0c836] | 76 | def inplace_change(filename, old_string, new_string): |
---|
| 77 | # Thanks to http://stackoverflow.com/questions/4128144/replace-string-within-file-contents |
---|
| 78 | s=open(filename).read() |
---|
| 79 | if old_string in s: |
---|
| 80 | print 'Changing "{old_string}" to "{new_string}"'.format(**locals()) |
---|
| 81 | s=s.replace(old_string, new_string) |
---|
| 82 | f=open(filename, 'w') |
---|
| 83 | f.write(s) |
---|
| 84 | f.flush() |
---|
| 85 | f.close() |
---|
| 86 | else: |
---|
| 87 | print 'No occurences of "{old_string}" found.'.format(**locals()) |
---|
| 88 | |
---|
[35bf493] | 89 | def _remove_dir(dir_path): |
---|
| 90 | """Removes the given directory.""" |
---|
| 91 | if os.path.isdir(dir_path): |
---|
| 92 | print "Removing \"%s\"... " % dir_path |
---|
| 93 | shutil.rmtree(dir_path) |
---|
| 94 | |
---|
| 95 | def clean(): |
---|
| 96 | """ |
---|
| 97 | Clean the sphinx build directory. |
---|
| 98 | """ |
---|
| 99 | print "=== Cleaning Sphinx Build ===" |
---|
| 100 | _remove_dir(SASVIEW_DOCS) |
---|
| 101 | _remove_dir(SPHINX_BUILD) |
---|
[7168b8b] | 102 | _remove_dir(SPHINX_SOURCE_GUIFRAME) |
---|
| 103 | _remove_dir(SPHINX_SOURCE_MODELS) |
---|
| 104 | _remove_dir(SPHINX_SOURCE_PERSPECTIVES) |
---|
[2fb09c4] | 105 | _remove_dir(SPHINX_SOURCE_TEST) |
---|
[35bf493] | 106 | |
---|
[354524d] | 107 | |
---|
[35bf493] | 108 | def retrieve_user_docs(): |
---|
| 109 | """ |
---|
| 110 | Copies across the contents of any media/ directories in src/, and puts them |
---|
| 111 | in an appropriately named directory of docs/sphinx-docs/source/. For |
---|
| 112 | example: |
---|
| 113 | |
---|
| 114 | sas/../[MODULE]/media/dir/A.rst |
---|
| 115 | sas/../[MODULE]/media/B.rst |
---|
| 116 | |
---|
| 117 | gets copied to a new location: |
---|
| 118 | |
---|
| 119 | docs/sphinx-docs/source/user/[MODULE]/dir/A.rst |
---|
| 120 | docs/sphinx-docs/source/user/[MODULE]/B.rst |
---|
| 121 | |
---|
| 122 | so that Sphinx may pick it up when generating the documentation. |
---|
| 123 | """ |
---|
| 124 | print "=== Retrieve User Docs ===" |
---|
| 125 | |
---|
| 126 | # Copy documentation files from their "source" to their "destination". |
---|
| 127 | for root, dirnames, _ in os.walk(SASVIEW_SRC): |
---|
| 128 | for dirname in fnmatch.filter(dirnames, 'media'): |
---|
| 129 | |
---|
| 130 | docs = os.path.abspath(os.path.join(root, dirname)) |
---|
| 131 | print "Found docs folder at \"%s\"." % docs |
---|
| 132 | |
---|
[f620870] | 133 | dest_dir_part = os.path.dirname(os.path.relpath(docs, SASVIEW_SRC)) |
---|
| 134 | if os.sep in dest_dir_part: |
---|
| 135 | dest_dir_part = dest_dir_part[dest_dir_part.index(os.sep) + 1:] |
---|
| 136 | dest_dir = os.path.join(SPHINX_SOURCE, "user", dest_dir_part) |
---|
[35bf493] | 137 | |
---|
| 138 | copy_tree(docs, dest_dir) |
---|
[2fb09c4] | 139 | |
---|
| 140 | # Now pickup testdata_help.rst |
---|
| 141 | # print os.path.abspath(SASVIEW_TEST) |
---|
| 142 | # print os.path.abspath(SPHINX_SOURCE_TEST) |
---|
[354524d] | 143 | print "=== Including Test Data Docs ===" |
---|
[2fb09c4] | 144 | if os.path.exists(SASVIEW_TEST): |
---|
| 145 | print "Found docs folder at ", SASVIEW_TEST |
---|
| 146 | shutil.copytree(SASVIEW_TEST, SPHINX_SOURCE_TEST) |
---|
[354524d] | 147 | |
---|
| 148 | print "=== And the Sasmodels Docs ===" |
---|
[6a9c0e5a] | 149 | # Make sure we have the relevant images for the new sasmodels documentation |
---|
[5420ef6] | 150 | # First(!) we'll make a local reference copy for SasView (/new-models will be cleaned each build) |
---|
[b7a2ebfd] | 151 | if os.path.exists(SASMODELS_SOURCE_IMG): |
---|
| 152 | print "Found img folder SASMODELS_SOURCE_IMG at ", SASMODELS_SOURCE_IMG |
---|
[6de5e10] | 153 | if not os.path.exists(SASMODELS_DEST_IMG): |
---|
| 154 | print "Missing docs folder SASMODELS_DEST_IMG at ", SASMODELS_DEST_IMG |
---|
| 155 | os.makedirs(SASMODELS_DEST_IMG) |
---|
| 156 | print "created SASMODELS_DEST_BUILDIMG at ", SASMODELS_DEST_BUILDIMG |
---|
| 157 | else: print "Found img folder SASMODELS_DEST_IMG at ", SASMODELS_DEST_IMG |
---|
| 158 | print "Copying sasmodels model image files..." |
---|
| 159 | for files in os.listdir(SASMODELS_SOURCE_IMG): |
---|
| 160 | fromhere=os.path.join(SASMODELS_SOURCE_IMG,files) |
---|
| 161 | tohere=os.path.join(SASMODELS_DEST_IMG,files) |
---|
| 162 | shutil.copy(fromhere,tohere) |
---|
| 163 | else: print "cannot find SASMODELS_SOURCE_IMG", SASMODELS_SOURCE_IMG |
---|
[b7a2ebfd] | 164 | |
---|
[5420ef6] | 165 | if os.path.exists(SASMODELS_SOURCE_AUTOIMG): |
---|
| 166 | print "Found img folder SASMODELS_SOURCE_AUTOIMG at ", SASMODELS_SOURCE_AUTOIMG |
---|
[6de5e10] | 167 | if not os.path.exists(SASMODELS_DEST_IMG): |
---|
[eff1a8fc] | 168 | print "Missing docs folder SASMODELS_DEST_IMG at ", SASMODELS_DEST_IMG |
---|
[6de5e10] | 169 | os.makedirs(SASMODELS_DEST_BUILDIMG) |
---|
| 170 | print "created SASMODELS_DEST_BUILDIMG at ", SASMODELS_DEST_BUILDIMG |
---|
| 171 | print "Copying sasmodels model auto-generated image files..." |
---|
| 172 | for files in os.listdir(SASMODELS_SOURCE_AUTOIMG): |
---|
| 173 | fromhere=os.path.join(SASMODELS_SOURCE_AUTOIMG,files) |
---|
| 174 | tohere=os.path.join(SASMODELS_DEST_IMG,files) |
---|
| 175 | shutil.copy(fromhere,tohere) |
---|
| 176 | else: print "no source directorty",SASMODELS_SOURCE_AUTOIMG ,"was found" |
---|
[5420ef6] | 177 | |
---|
[a728658] | 178 | # And the rst prolog with the unit substitutions |
---|
| 179 | if os.path.exists(SASMODELS_SOURCE_PROLOG): |
---|
| 180 | print "Found prolog folder SASMODELS_SOURCE_PROLOG at ", SASMODELS_SOURCE_PROLOG |
---|
| 181 | if os.path.exists(SASMODELS_DEST_PROLOG): |
---|
| 182 | print "Found docs folder SASMODELS_DEST_PROLOG at ", SASMODELS_DEST_PROLOG |
---|
| 183 | print "Copying sasmodels rst_prolog file..." |
---|
| 184 | for files in os.listdir(SASMODELS_SOURCE_PROLOG): |
---|
| 185 | if files.startswith("rst"): |
---|
| 186 | fromhere=os.path.join(SASMODELS_SOURCE_PROLOG,files) |
---|
| 187 | tohere=os.path.join(SASMODELS_DEST_PROLOG,files) |
---|
| 188 | shutil.copy(fromhere,tohere) |
---|
| 189 | |
---|
[18a1f2b] | 190 | if os.path.exists(SASMODELS_SOURCE_MAGNETISM): |
---|
| 191 | print "Found docs folder SASMODELS_SOURCE_MAGNETISM at ", SASMODELS_SOURCE_MAGNETISM |
---|
| 192 | if os.path.exists(SASMODELS_DEST_REF_MODELS): |
---|
| 193 | print "Found docs folder SASMODELS_DEST_REF_MODELS at ", SASMODELS_DEST_REF_MODELS |
---|
| 194 | print "Copying sasmodels model toctree files..." |
---|
| 195 | for files in os.listdir(SASMODELS_SOURCE_MAGNETISM): |
---|
| 196 | if files.endswith(".rst"): |
---|
| 197 | fromhere=os.path.join(SASMODELS_SOURCE_MAGNETISM,files) |
---|
| 198 | tohere=os.path.join(SASMODELS_DEST_REF_MODELS,files) |
---|
| 199 | shutil.copy(fromhere,tohere) |
---|
| 200 | |
---|
[bb0c836] | 201 | if os.path.exists(SASMODELS_SOURCE_REF_MODELS): |
---|
| 202 | print "Found docs folder SASMODELS_SOURCE_REF_MODELS at ", SASMODELS_SOURCE_REF_MODELS |
---|
| 203 | if os.path.exists(SASMODELS_DEST_REF_MODELS): |
---|
| 204 | print "Found docs folder SASMODELS_DEST_REF_MODELS at ", SASMODELS_DEST_REF_MODELS |
---|
| 205 | print "Copying sasmodels model toctree files..." |
---|
| 206 | for files in os.listdir(SASMODELS_SOURCE_REF_MODELS): |
---|
| 207 | if files.endswith(".rst"): |
---|
| 208 | fromhere=os.path.join(SASMODELS_SOURCE_REF_MODELS,files) |
---|
| 209 | tohere=os.path.join(SASMODELS_DEST_REF_MODELS,files) |
---|
| 210 | shutil.copy(fromhere,tohere) |
---|
| 211 | # But need to change the path to the model docs in the tocs |
---|
| 212 | for files in os.listdir(SASMODELS_DEST_REF_MODELS): |
---|
| 213 | # print files |
---|
| 214 | if files.startswith("shape"): |
---|
| 215 | print "Changing toc paths in", files |
---|
| 216 | inplace_change(os.path.join(SASMODELS_DEST_REF_MODELS,files), "../../model/", "models/") |
---|
| 217 | if files.startswith("sphere"): |
---|
| 218 | print "Changing toc paths in", files |
---|
| 219 | inplace_change(os.path.join(SASMODELS_DEST_REF_MODELS,files), "../../model/", "models/") |
---|
| 220 | if files.startswith("custom"): |
---|
| 221 | print "Changing toc paths in", files |
---|
| 222 | inplace_change(os.path.join(SASMODELS_DEST_REF_MODELS,files), "../../model/", "models/") |
---|
| 223 | if files.startswith("structure"): |
---|
| 224 | print "Changing toc paths in", files |
---|
| 225 | inplace_change(os.path.join(SASMODELS_DEST_REF_MODELS,files), "../../model/", "models/") |
---|
[a728658] | 226 | |
---|
[b7a2ebfd] | 227 | if os.path.exists(SASMODELS_SOURCE_MODELS): |
---|
| 228 | print "Found docs folder SASMODELS_SOURCE_MODELS at ", SASMODELS_SOURCE_MODELS |
---|
| 229 | if os.path.exists(SASMODELS_DEST_MODELS): |
---|
| 230 | print "Found docs folder SASMODELS_DEST_MODELS at ", SASMODELS_DEST_MODELS |
---|
[a728658] | 231 | print "Copying sasmodels model files..." |
---|
[b7a2ebfd] | 232 | for files in os.listdir(SASMODELS_SOURCE_MODELS): |
---|
[354524d] | 233 | if files.endswith(".rst"): |
---|
[b7a2ebfd] | 234 | fromhere=os.path.join(SASMODELS_SOURCE_MODELS,files) |
---|
| 235 | tohere=os.path.join(SASMODELS_DEST_MODELS,files) |
---|
| 236 | shutil.copy(fromhere,tohere) |
---|
[5420ef6] | 237 | else: |
---|
| 238 | print "Missing docs folder SASMODELS_DEST_MODELS at ", SASMODELS_DEST_MODELS |
---|
| 239 | os.makedirs(SASMODELS_DEST_MODELS) |
---|
| 240 | if not os.path.exists(SASMODELS_DEST_BUILDIMG): |
---|
| 241 | os.makedirs(SASMODELS_DEST_BUILDIMG) |
---|
| 242 | print "Created docs folder SASMODELS_DEST_MODELS at ", SASMODELS_DEST_MODELS |
---|
| 243 | print "Copying model files for build..." |
---|
| 244 | for files in os.listdir(SASMODELS_SOURCE_MODELS): |
---|
| 245 | if files.endswith(".rst"): |
---|
| 246 | fromhere=os.path.join(SASMODELS_SOURCE_MODELS,files) |
---|
| 247 | tohere=os.path.join(SASMODELS_DEST_MODELS,files) |
---|
| 248 | shutil.copy(fromhere,tohere) |
---|
| 249 | # No choice but to do this because model files are all coded for images in /models/img |
---|
| 250 | print "Copying image files for build..." |
---|
| 251 | for files in os.listdir(SASMODELS_DEST_IMG): |
---|
| 252 | fromhere=os.path.join(SASMODELS_DEST_IMG,files) |
---|
| 253 | tohere=os.path.join(SASMODELS_DEST_BUILDIMG,files) |
---|
| 254 | shutil.copy(fromhere,tohere) |
---|
[6a9c0e5a] | 255 | |
---|
[35bf493] | 256 | |
---|
[c22c5e3] | 257 | def retrieve_bumps_docs(): |
---|
| 258 | """ |
---|
| 259 | Copies select files from the bumps documentation into fitting perspective |
---|
| 260 | """ |
---|
| 261 | if os.path.exists(BUMPS_DOCS): |
---|
| 262 | print "=== Retrieve BUMPS Docs ===" |
---|
| 263 | filenames = [os.path.join(BUMPS_DOCS, "optimizer.rst")] |
---|
| 264 | filenames += glob(os.path.join(BUMPS_DOCS, "dream-*.png")) |
---|
| 265 | filenames += glob(os.path.join(BUMPS_DOCS, "fit-*.png")) |
---|
| 266 | for f in filenames: |
---|
| 267 | print "Copying file", f |
---|
| 268 | shutil.copy(f, BUMPS_TARGET) |
---|
| 269 | else: |
---|
| 270 | print """ |
---|
| 271 | *** Error *** missing directory %s |
---|
| 272 | The documentation will not include the optimizer selection section. |
---|
| 273 | Checkout the bumps source tree and rebuild the docs. |
---|
| 274 | |
---|
| 275 | |
---|
| 276 | """ % BUMPS_DOCS |
---|
| 277 | |
---|
[35bf493] | 278 | def apidoc(): |
---|
| 279 | """ |
---|
| 280 | Runs sphinx-apidoc to generate .rst files from the docstrings in .py files |
---|
| 281 | in the SasView build directory. |
---|
| 282 | """ |
---|
| 283 | print "=== Generate API Rest Files ===" |
---|
| 284 | |
---|
| 285 | # Clean directory before generating a new version. |
---|
| 286 | _remove_dir(SPHINX_SOURCE_API) |
---|
| 287 | |
---|
| 288 | subprocess.call(["sphinx-apidoc", |
---|
| 289 | "-o", SPHINX_SOURCE_API, # Output dir. |
---|
| 290 | "-d", "8", # Max depth of TOC. |
---|
| 291 | SASVIEW_BUILD]) |
---|
| 292 | |
---|
| 293 | def build(): |
---|
| 294 | """ |
---|
| 295 | Runs sphinx-build. Reads in all .rst files and spits out the final html. |
---|
| 296 | """ |
---|
| 297 | print "=== Build HTML Docs from Rest Files ===" |
---|
| 298 | subprocess.call(["sphinx-build", |
---|
| 299 | "-b", "html", # Builder name. TODO: accept as arg to setup.py. |
---|
| 300 | "-d", os.path.join(SPHINX_BUILD, "doctrees"), |
---|
| 301 | SPHINX_SOURCE, |
---|
| 302 | os.path.join(SPHINX_BUILD, "html")]) |
---|
| 303 | |
---|
| 304 | print "=== Copy HTML Docs to Build Directory ===" |
---|
| 305 | html = os.path.join(SPHINX_BUILD, "html") |
---|
| 306 | copy_tree(html, SASVIEW_DOCS) |
---|
| 307 | |
---|
[c2ee2b1] | 308 | def rebuild(): |
---|
[35bf493] | 309 | clean() |
---|
| 310 | retrieve_user_docs() |
---|
[c22c5e3] | 311 | retrieve_bumps_docs() |
---|
[35bf493] | 312 | apidoc() |
---|
| 313 | build() |
---|
[c2ee2b1] | 314 | |
---|
| 315 | print "=== Done ===" |
---|
| 316 | |
---|
| 317 | if __name__ == "__main__": |
---|
[9bf64f6] | 318 | rebuild() |
---|