source: sasview/docs/sphinx-docs/build_sphinx.py @ 25427d9

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.2release_4.0.1ticket-1009ticket-1094-headlessticket-1242-2d-resolutionticket-1243ticket-1249ticket885unittest-saveload
Last change on this file since 25427d9 was bb0c836, checked in by smk78, 9 years ago

SasView? build-sphinx now slurps the sasmodels toc files and
automatically changes the paths

  • Property mode set to 100755
File size: 11.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")
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_REF_MODELS = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", "sasmodels", "doc", "ref", "models")
38SASMODELS_SOURCE_MODELS = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", "sasmodels", "doc", "model")
39SASMODELS_SOURCE_IMG = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..", "sasmodels", "doc", "model", "img")
40SASMODELS_DEST_PROLOG = os.path.join(CURRENT_SCRIPT_DIR, "source")
41SASMODELS_DEST_REF_MODELS = os.path.join(CURRENT_SCRIPT_DIR, "source", "user")
42SASMODELS_DEST_MODELS = os.path.join(CURRENT_SCRIPT_DIR, "source", "user", "models")
43SASMODELS_DEST_IMG = os.path.join(CURRENT_SCRIPT_DIR,  "source", "user", "models", "img")
44
45#if os.path.exists(SASMODELS_SOURCE_PROLOG):
46#    print "Found models prolog folder at ", SASMODELS_SOURCE_PROLOG
47#if os.path.exists(SASMODELS_SOURCE_REF_MODELS):
48#    print "Found models ref folder at ", SASMODELS_SOURCE_REF_MODELS
49#if os.path.exists(SASMODELS_SOURCE_MODELS):
50#    print "Found models folder at ", SASMODELS_SOURCE_MODELS
51#if os.path.exists(SASMODELS_SOURCE_IMG):
52#    print "Found img folder at ", SASMODELS_SOURCE_IMG
53#if os.path.exists(SASMODELS_DEST_REF_MODELS):
54#    print "Found models ref folder at ", SASMODELS_DEST_REF_MODELS
55#if os.path.exists(SASMODELS_DEST_MODELS):
56#    print "Found models folder at ", SASMODELS_DEST_MODELS
57#if os.path.exists(SASMODELS_DEST_IMG):
58#    print "Found img folder at ", SASMODELS_DEST_IMG
59#sys.exit()
60
61SPHINX_BUILD = os.path.join(CURRENT_SCRIPT_DIR, "build")
62SPHINX_SOURCE = os.path.join(CURRENT_SCRIPT_DIR, "source")
63SPHINX_SOURCE_API = os.path.join(SPHINX_SOURCE, "dev", "api")
64SPHINX_SOURCE_GUIFRAME = os.path.join(SPHINX_SOURCE, "user", "sasgui", "guiframe")
65SPHINX_SOURCE_MODELS = os.path.join(SPHINX_SOURCE, "user", "models")
66SPHINX_SOURCE_PERSPECTIVES = os.path.join(SPHINX_SOURCE, "user", "sasgui", "perspectives")
67SPHINX_SOURCE_TEST = os.path.join(SPHINX_SOURCE, "test")
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_GUIFRAME)
100    _remove_dir(SPHINX_SOURCE_MODELS)
101    _remove_dir(SPHINX_SOURCE_PERSPECTIVES)
102    _remove_dir(SPHINX_SOURCE_TEST)
103
104
105def retrieve_user_docs():
106    """
107    Copies across the contents of any media/ directories in src/, and puts them
108    in an appropriately named directory of docs/sphinx-docs/source/. For
109    example:
110
111        sas/../[MODULE]/media/dir/A.rst
112        sas/../[MODULE]/media/B.rst
113
114    gets copied to a new location:
115
116        docs/sphinx-docs/source/user/[MODULE]/dir/A.rst
117        docs/sphinx-docs/source/user/[MODULE]/B.rst
118
119    so that Sphinx may pick it up when generating the documentation.
120    """
121    print "=== Retrieve User Docs ==="
122
123    # Copy documentation files from their "source" to their "destination".
124    for root, dirnames, _ in os.walk(SASVIEW_SRC):
125        for dirname in fnmatch.filter(dirnames, 'media'):
126
127            docs = os.path.abspath(os.path.join(root, dirname))
128            print "Found docs folder at \"%s\"." % docs
129
130            dest_dir_part = os.path.dirname(os.path.relpath(docs, SASVIEW_SRC))
131            if os.sep in dest_dir_part:
132                dest_dir_part = dest_dir_part[dest_dir_part.index(os.sep) + 1:]
133            dest_dir = os.path.join(SPHINX_SOURCE, "user", dest_dir_part)
134
135            copy_tree(docs, dest_dir)
136           
137    # Now pickup testdata_help.rst
138#    print os.path.abspath(SASVIEW_TEST)
139#    print os.path.abspath(SPHINX_SOURCE_TEST)
140    print "=== Including Test Data Docs ==="
141    if os.path.exists(SASVIEW_TEST):
142       print "Found docs folder at ", SASVIEW_TEST
143       shutil.copytree(SASVIEW_TEST, SPHINX_SOURCE_TEST)       
144
145    print "=== And the Sasmodels Docs ===" 
146    # Make sure we have the relevant images for the new sasmodels documentation
147    if os.path.exists(SASMODELS_SOURCE_IMG):
148        print "Found img  folder SASMODELS_SOURCE_IMG    at ", SASMODELS_SOURCE_IMG
149        if os.path.exists(SASMODELS_DEST_IMG):
150            print "Found img  folder SASMODELS_DEST_IMG      at ", SASMODELS_DEST_IMG
151            print "Copying sasmodels model image files..."
152            for files in os.listdir(SASMODELS_SOURCE_IMG):
153                fromhere=os.path.join(SASMODELS_SOURCE_IMG,files)
154                tohere=os.path.join(SASMODELS_DEST_IMG,files)
155                shutil.copy(fromhere,tohere)
156
157    # And the rst prolog with the unit substitutions
158    if os.path.exists(SASMODELS_SOURCE_PROLOG):
159        print "Found prolog folder SASMODELS_SOURCE_PROLOG at ", SASMODELS_SOURCE_PROLOG
160        if os.path.exists(SASMODELS_DEST_PROLOG):
161            print "Found docs folder SASMODELS_DEST_PROLOG   at ", SASMODELS_DEST_PROLOG
162            print "Copying sasmodels rst_prolog file..."
163            for files in os.listdir(SASMODELS_SOURCE_PROLOG):
164                if files.startswith("rst"):
165                    fromhere=os.path.join(SASMODELS_SOURCE_PROLOG,files)
166                    tohere=os.path.join(SASMODELS_DEST_PROLOG,files)
167                    shutil.copy(fromhere,tohere)
168
169    if os.path.exists(SASMODELS_SOURCE_REF_MODELS):
170        print "Found docs folder SASMODELS_SOURCE_REF_MODELS at ", SASMODELS_SOURCE_REF_MODELS
171        if os.path.exists(SASMODELS_DEST_REF_MODELS):
172            print "Found docs folder SASMODELS_DEST_REF_MODELS   at ", SASMODELS_DEST_REF_MODELS
173            print "Copying sasmodels model toctree files..."
174            for files in os.listdir(SASMODELS_SOURCE_REF_MODELS):
175                if files.endswith(".rst"):
176                    fromhere=os.path.join(SASMODELS_SOURCE_REF_MODELS,files)
177                    tohere=os.path.join(SASMODELS_DEST_REF_MODELS,files)
178                    shutil.copy(fromhere,tohere)
179    # But need to change the path to the model docs in the tocs
180    for files in os.listdir(SASMODELS_DEST_REF_MODELS):
181#        print files
182        if files.startswith("shape"):
183            print "Changing toc paths in", files
184            inplace_change(os.path.join(SASMODELS_DEST_REF_MODELS,files), "../../model/", "models/")
185        if files.startswith("sphere"):
186            print "Changing toc paths in", files
187            inplace_change(os.path.join(SASMODELS_DEST_REF_MODELS,files), "../../model/", "models/")
188        if files.startswith("custom"):
189            print "Changing toc paths in", files
190            inplace_change(os.path.join(SASMODELS_DEST_REF_MODELS,files), "../../model/", "models/")
191        if files.startswith("structure"):
192            print "Changing toc paths in", files
193            inplace_change(os.path.join(SASMODELS_DEST_REF_MODELS,files), "../../model/", "models/")
194
195    if os.path.exists(SASMODELS_SOURCE_MODELS):
196        print "Found docs folder SASMODELS_SOURCE_MODELS at ", SASMODELS_SOURCE_MODELS
197        if os.path.exists(SASMODELS_DEST_MODELS):
198            print "Found docs folder SASMODELS_DEST_MODELS   at ", SASMODELS_DEST_MODELS
199            print "Copying sasmodels model files..."
200            for files in os.listdir(SASMODELS_SOURCE_MODELS):
201                if files.endswith(".rst"):
202                    fromhere=os.path.join(SASMODELS_SOURCE_MODELS,files)
203                    tohere=os.path.join(SASMODELS_DEST_MODELS,files)
204                    shutil.copy(fromhere,tohere)
205
206
207def retrieve_bumps_docs():
208    """
209    Copies select files from the bumps documentation into fitting perspective
210    """
211    if os.path.exists(BUMPS_DOCS):
212        print "=== Retrieve BUMPS Docs ==="
213        filenames = [os.path.join(BUMPS_DOCS, "optimizer.rst")]
214        filenames += glob(os.path.join(BUMPS_DOCS, "dream-*.png"))
215        filenames += glob(os.path.join(BUMPS_DOCS, "fit-*.png"))
216        for f in filenames:
217            print "Copying file", f
218            shutil.copy(f, BUMPS_TARGET)
219    else:
220        print """
221*** Error *** missing directory %s
222The documentation will not include the optimizer selection section.
223Checkout the bumps source tree and rebuild the docs.
224
225
226""" % BUMPS_DOCS
227
228def apidoc():
229    """
230    Runs sphinx-apidoc to generate .rst files from the docstrings in .py files
231    in the SasView build directory.
232    """
233    print "=== Generate API Rest Files ==="
234
235    # Clean directory before generating a new version.
236    _remove_dir(SPHINX_SOURCE_API)
237
238    subprocess.call(["sphinx-apidoc",
239                     "-o", SPHINX_SOURCE_API, # Output dir.
240                     "-d", "8", # Max depth of TOC.
241                     SASVIEW_BUILD])
242
243def build():
244    """
245    Runs sphinx-build.  Reads in all .rst files and spits out the final html.
246    """
247    print "=== Build HTML Docs from Rest Files ==="
248    subprocess.call(["sphinx-build",
249                     "-b", "html", # Builder name. TODO: accept as arg to setup.py.
250                     "-d", os.path.join(SPHINX_BUILD, "doctrees"),
251                     SPHINX_SOURCE,
252                     os.path.join(SPHINX_BUILD, "html")])
253
254    print "=== Copy HTML Docs to Build Directory ==="
255    html = os.path.join(SPHINX_BUILD, "html")
256    copy_tree(html, SASVIEW_DOCS)
257
258def rebuild():
259    clean()
260    retrieve_user_docs()
261    retrieve_bumps_docs()
262    apidoc()
263    build()
264
265    print "=== Done ==="
266
267if __name__ == "__main__":
268    rebuild()
Note: See TracBrowser for help on using the repository browser.