source: sasview/docs/sphinx-docs/build_sphinx.py @ 21bba86

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 21bba86 was 21bba86, checked in by ajj, 7 years ago

More print fixes

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