source: sasview/docs/sphinx-docs/build_sphinx.py @ c22c5e3

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 c22c5e3 was c22c5e3, checked in by Paul Kienzle <pkienzle@…>, 9 years ago

copy bumps optimizer docs into sasview docs, if available

  • Property mode set to 100644
File size: 4.8 KB
Line 
1"""
2Functions for building sphinx docs.
3
4For more information on the invocation of sphinx see:
5http://sphinx-doc.org/invocation.html
6"""
7import subprocess
8import os
9import sys
10import fnmatch
11import shutil
12import imp
13from glob import glob
14
15from distutils.dir_util import copy_tree
16from distutils.util import get_platform
17
18platform = '.%s-%s'%(get_platform(),sys.version[:3])
19
20CURRENT_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
21
22run = imp.load_source('run', os.path.join(CURRENT_SCRIPT_DIR, '..', '..', 'run.py'))
23run.prepare()
24
25SASVIEW_SRC = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "src")
26SASVIEW_BUILD = os.path.abspath(os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "build", "lib"+platform))
27SASVIEW_DOCS = os.path.join(SASVIEW_BUILD, "doc")
28
29SPHINX_BUILD = os.path.join(CURRENT_SCRIPT_DIR, "build")
30SPHINX_SOURCE = os.path.join(CURRENT_SCRIPT_DIR, "source")
31SPHINX_SOURCE_API = os.path.join(SPHINX_SOURCE, "dev", "api")
32SPHINX_SOURCE_GUIFRAME = os.path.join(SPHINX_SOURCE, "user", "guiframe")
33SPHINX_SOURCE_MODELS = os.path.join(SPHINX_SOURCE, "user", "models")
34SPHINX_SOURCE_PERSPECTIVES = os.path.join(SPHINX_SOURCE, "user", "perspectives")
35
36BUMPS_DOCS = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "..",
37                          "bumps", "doc", "guide")
38BUMPS_TARGET = os.path.join(SPHINX_SOURCE_PERSPECTIVES, "fitting")
39
40def _remove_dir(dir_path):
41    """Removes the given directory."""
42    if os.path.isdir(dir_path):
43        print "Removing \"%s\"... " % dir_path
44        shutil.rmtree(dir_path)
45
46def clean():
47    """
48    Clean the sphinx build directory.
49    """
50    print "=== Cleaning Sphinx Build ==="
51    _remove_dir(SASVIEW_DOCS)
52    _remove_dir(SPHINX_BUILD)
53    _remove_dir(SPHINX_SOURCE_GUIFRAME)
54    _remove_dir(SPHINX_SOURCE_MODELS)
55    _remove_dir(SPHINX_SOURCE_PERSPECTIVES)
56
57def retrieve_user_docs():
58    """
59    Copies across the contents of any media/ directories in src/, and puts them
60    in an appropriately named directory of docs/sphinx-docs/source/. For
61    example:
62
63        sas/../[MODULE]/media/dir/A.rst
64        sas/../[MODULE]/media/B.rst
65
66    gets copied to a new location:
67
68        docs/sphinx-docs/source/user/[MODULE]/dir/A.rst
69        docs/sphinx-docs/source/user/[MODULE]/B.rst
70
71    so that Sphinx may pick it up when generating the documentation.
72    """
73    print "=== Retrieve User Docs ==="
74
75    # Copy documentation files from their "source" to their "destination".
76    for root, dirnames, _ in os.walk(SASVIEW_SRC):
77        for dirname in fnmatch.filter(dirnames, 'media'):
78
79            docs = os.path.abspath(os.path.join(root, dirname))
80            print "Found docs folder at \"%s\"." % docs
81
82            dest_dir_part = os.path.dirname(os.path.relpath(docs, SASVIEW_SRC))
83            if os.sep in dest_dir_part:
84                dest_dir_part = dest_dir_part[dest_dir_part.index(os.sep) + 1:]
85            dest_dir = os.path.join(SPHINX_SOURCE, "user", dest_dir_part)
86
87            copy_tree(docs, dest_dir)
88
89def retrieve_bumps_docs():
90    """
91    Copies select files from the bumps documentation into fitting perspective
92    """
93    if os.path.exists(BUMPS_DOCS):
94        print "=== Retrieve BUMPS Docs ==="
95        filenames = [os.path.join(BUMPS_DOCS, "optimizer.rst")]
96        filenames += glob(os.path.join(BUMPS_DOCS, "dream-*.png"))
97        filenames += glob(os.path.join(BUMPS_DOCS, "fit-*.png"))
98        for f in filenames:
99            print "Copying file", f
100            shutil.copy(f, BUMPS_TARGET)
101    else:
102        print """
103*** Error *** missing directory %s
104The documentation will not include the optimizer selection section.
105Checkout the bumps source tree and rebuild the docs.
106
107
108""" % BUMPS_DOCS
109
110def apidoc():
111    """
112    Runs sphinx-apidoc to generate .rst files from the docstrings in .py files
113    in the SasView build directory.
114    """
115    print "=== Generate API Rest Files ==="
116
117    # Clean directory before generating a new version.
118    _remove_dir(SPHINX_SOURCE_API)
119
120    subprocess.call(["sphinx-apidoc",
121                     "-o", SPHINX_SOURCE_API, # Output dir.
122                     "-d", "8", # Max depth of TOC.
123                     SASVIEW_BUILD])
124
125def build():
126    """
127    Runs sphinx-build.  Reads in all .rst files and spits out the final html.
128    """
129    print "=== Build HTML Docs from Rest Files ==="
130    subprocess.call(["sphinx-build",
131                     "-b", "html", # Builder name. TODO: accept as arg to setup.py.
132                     "-d", os.path.join(SPHINX_BUILD, "doctrees"),
133                     SPHINX_SOURCE,
134                     os.path.join(SPHINX_BUILD, "html")])
135
136    print "=== Copy HTML Docs to Build Directory ==="
137    html = os.path.join(SPHINX_BUILD, "html")
138    copy_tree(html, SASVIEW_DOCS)
139
140if __name__ == "__main__":
141    clean()
142    retrieve_user_docs()
143    retrieve_bumps_docs()
144    apidoc()
145    build()
146       
147    print "=== Done ==="
Note: See TracBrowser for help on using the repository browser.