source: sasview/docs/sphinx-docs/build_sphinx.py @ dd72190

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.2ticket-1009ticket-1094-headlessticket-1242-2d-resolutionticket-1243ticket-1249ticket885unittest-saveload
Last change on this file since dd72190 was dd72190, checked in by ajj, 7 years ago

Doc build script update to include sesans images

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