source: sasview/docs/sphinx-docs/build_sphinx.py @ 01f1e17

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

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