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