source: sasview/docs/sphinx-docs/build_sphinx.py @ 80a49c2

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.2.2ticket-1009ticket-1094-headlessticket-1242-2d-resolutionticket-1243ticket-1249ticket885unittest-saveload
Last change on this file since 80a49c2 was 751f4bd, checked in by smk78, 8 years ago

SESANS fitting instructions now linked in sasview also. Closes #720

  • Property mode set to 100755
File size: 18.0 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    if os.path.exists(SASMODELS_SOURCE_SESANS):
221        print "Found docs folder SASMODELS_SOURCE_SESANS at ", SASMODELS_SOURCE_SESANS
222        if os.path.exists(SPHINX_SOURCE_USER):
223            print "Found docs folder SPHINX_SOURCE_USER      at ", SPHINX_SOURCE_USER
224            print "Copying sasmodels sesans files..."
225            for files in os.listdir(SASMODELS_SOURCE_SESANS):
226                if files.endswith(".rst"):
227                    fromhere=os.path.join(SASMODELS_SOURCE_SESANS,files)
228                    tohere=os.path.join(SPHINX_SOURCE_USER,files)
229                    shutil.copy(fromhere,tohere)
230
231    if os.path.exists(SASMODELS_SOURCE_MAGNETISM):
232        print "Found docs folder SASMODELS_SOURCE_MAGNETISM at ", SASMODELS_SOURCE_MAGNETISM
233        if os.path.exists(SASMODELS_DEST_REF_MODELS):
234            print "Found docs folder SASMODELS_DEST_REF_MODELS   at ", SASMODELS_DEST_REF_MODELS
235            print "Copying sasmodels model toctree files..."
236            for files in os.listdir(SASMODELS_SOURCE_MAGNETISM):
237                if files.endswith(".rst"):
238                    fromhere=os.path.join(SASMODELS_SOURCE_MAGNETISM,files)
239                    tohere=os.path.join(SASMODELS_DEST_REF_MODELS,files)
240                    shutil.copy(fromhere,tohere)
241
242    if os.path.exists(SASMODELS_SOURCE_MAGIMG):
243        print "Found img folder SASMODELS_SOURCE_MAGIMG   at ", SASMODELS_SOURCE_MAGIMG
244        if not os.path.exists(SASMODELS_DEST_MAGIMG):
245            print "Missing img folder SASMODELS_DEST_MAGIMG at ", SASMODELS_DEST_MAGIMG
246            os.makedirs(SASMODELS_DEST_MAGIMG)
247            print "created SASMODELS_DEST_MAGIMG at ", SASMODELS_DEST_MAGIMG
248        print "Copying sasmodels mag image files..."
249        for files in os.listdir(SASMODELS_SOURCE_MAGIMG):
250            fromhere=os.path.join(SASMODELS_SOURCE_MAGIMG,files)
251            tohere=os.path.join(SASMODELS_DEST_MAGIMG,files)
252            shutil.copy(fromhere,tohere)
253    else: print "no source directory",SASMODELS_SOURCE_MAGIMG ,"was found"
254
255    if os.path.exists(SASMODELS_SOURCE_SESANSIMG):
256        print "Found img folder SASMODELS_SOURCE_SESANSIMG   at ", SASMODELS_SOURCE_SESANSIMG
257        if not os.path.exists(SASMODELS_DEST_SESANSIMG):
258            print "Missing img folder SASMODELS_DEST_SESANSIMG at ", SASMODELS_DEST_SESANSIMG
259            os.makedirs(SASMODELS_DEST_SESANSIMG)
260            print "created SASMODELS_DEST_SESANSIMG at ", SASMODELS_DEST_SESANSIMG
261        print "Copying sasmodels sesans image files..."
262        for files in os.listdir(SASMODELS_SOURCE_SESANSIMG):
263            fromhere=os.path.join(SASMODELS_SOURCE_SESANSIMG,files)
264            tohere=os.path.join(SASMODELS_DEST_SESANSIMG,files)
265            shutil.copy(fromhere,tohere)
266    else: print "no source directory",SASMODELS_SOURCE_SESANSIMG ,"was found"
267
268    if os.path.exists(SASMODELS_SOURCE_REF_MODELS):
269        print "Found docs folder SASMODELS_SOURCE_REF_MODELS at ", SASMODELS_SOURCE_REF_MODELS
270        if os.path.exists(SASMODELS_DEST_REF_MODELS):
271            print "Found docs folder SASMODELS_DEST_REF_MODELS   at ", SASMODELS_DEST_REF_MODELS
272            print "Copying sasmodels model toctree files..."
273            for files in os.listdir(SASMODELS_SOURCE_REF_MODELS):
274                if files.endswith(".rst"):
275                    fromhere=os.path.join(SASMODELS_SOURCE_REF_MODELS,files)
276                    tohere=os.path.join(SASMODELS_DEST_REF_MODELS,files)
277                    shutil.copy(fromhere,tohere)
278    # But need to change the path to the model docs in the tocs
279    for files in os.listdir(SASMODELS_DEST_REF_MODELS):
280#        print files
281        if files.startswith("shape"):
282            print "Changing toc paths in", files
283            inplace_change(os.path.join(SASMODELS_DEST_REF_MODELS,files), "../../model/", "models/")
284        if files.startswith("sphere"):
285            print "Changing toc paths in", files
286            inplace_change(os.path.join(SASMODELS_DEST_REF_MODELS,files), "../../model/", "models/")
287        if files.startswith("custom"):
288            print "Changing toc paths in", files
289            inplace_change(os.path.join(SASMODELS_DEST_REF_MODELS,files), "../../model/", "models/")
290        if files.startswith("structure"):
291            print "Changing toc paths in", files
292            inplace_change(os.path.join(SASMODELS_DEST_REF_MODELS,files), "../../model/", "models/")
293
294    if os.path.exists(SASMODELS_SOURCE_MODELS):
295        print "Found docs folder SASMODELS_SOURCE_MODELS at ", SASMODELS_SOURCE_MODELS
296        if os.path.exists(SASMODELS_DEST_MODELS):
297            print "Found docs folder SASMODELS_DEST_MODELS   at ", SASMODELS_DEST_MODELS
298            print "Copying sasmodels model files..."
299            for files in os.listdir(SASMODELS_SOURCE_MODELS):
300                if files.endswith(".rst"):
301                    fromhere=os.path.join(SASMODELS_SOURCE_MODELS,files)
302                    tohere=os.path.join(SASMODELS_DEST_MODELS,files)
303                    shutil.copy(fromhere,tohere)
304        else:
305            print "Missing docs folder SASMODELS_DEST_MODELS at ", SASMODELS_DEST_MODELS
306            os.makedirs(SASMODELS_DEST_MODELS)
307            if not os.path.exists(SASMODELS_DEST_BUILDIMG):
308                os.makedirs(SASMODELS_DEST_BUILDIMG)
309            print "Created docs folder SASMODELS_DEST_MODELS at ", SASMODELS_DEST_MODELS
310            print "Copying model files for build..."
311            for files in os.listdir(SASMODELS_SOURCE_MODELS):
312                if files.endswith(".rst"):
313                    fromhere=os.path.join(SASMODELS_SOURCE_MODELS,files)
314                    tohere=os.path.join(SASMODELS_DEST_MODELS,files)
315                    shutil.copy(fromhere,tohere)
316            # No choice but to do this because model files are all coded for images in /models/img
317            print "Copying image files for build..."
318            for files in os.listdir(SASMODELS_DEST_IMG):
319                fromhere=os.path.join(SASMODELS_DEST_IMG,files)
320                tohere=os.path.join(SASMODELS_DEST_BUILDIMG,files)
321                shutil.copy(fromhere,tohere)
322
323
324def retrieve_bumps_docs():
325    """
326    Copies select files from the bumps documentation into fitting perspective
327    """
328    if os.path.exists(BUMPS_DOCS):
329        print "=== Retrieve BUMPS Docs ==="
330        filenames = [os.path.join(BUMPS_DOCS, "optimizer.rst")]
331        filenames += glob(os.path.join(BUMPS_DOCS, "dream-*.png"))
332        filenames += glob(os.path.join(BUMPS_DOCS, "fit-*.png"))
333        for f in filenames:
334            print "Copying file", f
335            shutil.copy(f, BUMPS_TARGET)
336    else:
337        print """
338*** Error *** missing directory %s
339The documentation will not include the optimizer selection section.
340Checkout the bumps source tree and rebuild the docs.
341
342
343""" % BUMPS_DOCS
344
345def apidoc():
346    """
347    Runs sphinx-apidoc to generate .rst files from the docstrings in .py files
348    in the SasView build directory.
349    """
350    print "=== Generate API Rest Files ==="
351
352    # Clean directory before generating a new version.
353    _remove_dir(SPHINX_SOURCE_API)
354
355    subprocess.call(["sphinx-apidoc",
356                     "-o", SPHINX_SOURCE_API, # Output dir.
357                     "-d", "8", # Max depth of TOC.
358                     SASVIEW_BUILD])
359
360def build():
361    """
362    Runs sphinx-build.  Reads in all .rst files and spits out the final html.
363    """
364    print "=== Build HTML Docs from Rest Files ==="
365    subprocess.call(["sphinx-build",
366                     "-b", "html", # Builder name. TODO: accept as arg to setup.py.
367                     "-d", os.path.join(SPHINX_BUILD, "doctrees"),
368                     SPHINX_SOURCE,
369                     os.path.join(SPHINX_BUILD, "html")])
370
371    print "=== Copy HTML Docs to Build Directory ==="
372    html = os.path.join(SPHINX_BUILD, "html")
373    copy_tree(html, SASVIEW_DOCS)
374
375def rebuild():
376    clean()
377    setup_source_temp()
378    retrieve_user_docs()
379    retrieve_bumps_docs()
380    apidoc()
381    build()
382
383    print "=== Done ==="
384
385if __name__ == "__main__":
386    rebuild()
Note: See TracBrowser for help on using the repository browser.