source: sasview/docs/sphinx-docs/build_sphinx.py @ 6673d2f

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 6673d2f 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
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")
32
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
36SASMODELS_SOURCE_PROLOG = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", "sasmodels", "doc")
37SASMODELS_SOURCE_MAGNETISM = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", "sasmodels", "doc", "ref", "magnetism")
38SASMODELS_SOURCE_MAGIMG = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", "sasmodels", "doc", "ref", "magnetism", "mag_img")
39SASMODELS_SOURCE_REF_MODELS = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", "sasmodels", "doc", "ref", "models")
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")
42SASMODELS_SOURCE_AUTOIMG = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", "sasmodels", "doc", "_build", "html","_images")
43SASMODELS_DEST_PROLOG = os.path.join(CURRENT_SCRIPT_DIR, "source")
44SASMODELS_DEST_REF_MODELS = os.path.join(CURRENT_SCRIPT_DIR, "source", "user")
45SASMODELS_DEST_MODELS = os.path.join(CURRENT_SCRIPT_DIR, "source", "user", "models")
46SASMODELS_DEST_IMG = os.path.join(CURRENT_SCRIPT_DIR,  "source", "user", "model-imgs", "new-models")
47SASMODELS_DEST_MAGIMG = os.path.join(CURRENT_SCRIPT_DIR,  "source", "user", "mag_img")
48SASMODELS_DEST_BUILDIMG = os.path.join(CURRENT_SCRIPT_DIR,  "source", "user", "models", "img")
49
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
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
58#if os.path.exists(SASMODELS_DEST_REF_MODELS):
59#    print "Found models ref folder at ", SASMODELS_DEST_REF_MODELS
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
64#sys.exit()
65
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")
69SPHINX_SOURCE_GUIFRAME = os.path.join(SPHINX_SOURCE, "user", "sasgui", "guiframe")
70SPHINX_SOURCE_MODELS = os.path.join(SPHINX_SOURCE, "user", "models")
71SPHINX_SOURCE_PERSPECTIVES = os.path.join(SPHINX_SOURCE, "user", "sasgui", "perspectives")
72SPHINX_SOURCE_TEST = os.path.join(SPHINX_SOURCE, "test")
73
74BUMPS_DOCS = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..",
75                          "bumps", "doc", "guide")
76BUMPS_TARGET = os.path.join(SPHINX_SOURCE_PERSPECTIVES, "fitting")
77
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
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)
104    _remove_dir(SPHINX_SOURCE_GUIFRAME)
105    _remove_dir(SPHINX_SOURCE_MODELS)
106    _remove_dir(SPHINX_SOURCE_PERSPECTIVES)
107    _remove_dir(SPHINX_SOURCE_TEST)
108
109
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
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)
139
140            copy_tree(docs, dest_dir)
141
142    # Now pickup testdata_help.rst
143#    print os.path.abspath(SASVIEW_TEST)
144#    print os.path.abspath(SPHINX_SOURCE_TEST)
145    print "=== Including Test Data Docs ==="
146    if os.path.exists(SASVIEW_TEST):
147       print "Found docs folder at ", SASVIEW_TEST
148       shutil.copytree(SASVIEW_TEST, SPHINX_SOURCE_TEST)
149
150    print "=== And the Sasmodels Docs ==="
151    # Make sure we have the relevant images for the new sasmodels documentation
152    # First(!) we'll make a local reference copy for SasView (/new-models will be cleaned each build)
153    if os.path.exists(SASMODELS_SOURCE_IMG):
154        print "Found img  folder SASMODELS_SOURCE_IMG    at ", SASMODELS_SOURCE_IMG
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
166
167    if os.path.exists(SASMODELS_SOURCE_AUTOIMG):
168        print "Found img  folder SASMODELS_SOURCE_AUTOIMG    at ", SASMODELS_SOURCE_AUTOIMG
169        if not os.path.exists(SASMODELS_DEST_IMG):
170            print "Missing docs folder SASMODELS_DEST_IMG at ", SASMODELS_DEST_IMG
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"
179
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
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
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
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/")
241
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
246            print "Copying sasmodels model files..."
247            for files in os.listdir(SASMODELS_SOURCE_MODELS):
248                if files.endswith(".rst"):
249                    fromhere=os.path.join(SASMODELS_SOURCE_MODELS,files)
250                    tohere=os.path.join(SASMODELS_DEST_MODELS,files)
251                    shutil.copy(fromhere,tohere)
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)
270
271
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
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
323def rebuild():
324    clean()
325    retrieve_user_docs()
326    retrieve_bumps_docs()
327    apidoc()
328    build()
329
330    print "=== Done ==="
331
332if __name__ == "__main__":
333    rebuild()
Note: See TracBrowser for help on using the repository browser.