source: sasview/docs/sphinx-docs/build_sphinx.py @ 578a11d

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 578a11d was 578a11d, checked in by smk78, 5 years ago

Implement sasmodels documantation on SANS to SESANS conversion in
sasview aswell.

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