source: sasview/docs/sphinx-docs/build_sphinx.py @ 8096b446

ESS_GUIESS_GUI_DocsESS_GUI_batch_fittingESS_GUI_bumps_abstractionESS_GUI_iss1116ESS_GUI_iss879ESS_GUI_iss959ESS_GUI_openclESS_GUI_orderingESS_GUI_sync_sascalccostrafo411magnetic_scattrelease-4.1.1release-4.1.2release-4.2.2release_4.0.1ticket-1009ticket-1094-headlessticket-1242-2d-resolutionticket-1243ticket-1249ticket885unittest-saveload
Last change on this file since 8096b446 was 8096b446, checked in by wojciech, 8 years ago

Sphinx build adds mag_img folder

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