source: sasview/docs/sphinx-docs/build_sphinx.py @ 892a2cc

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 892a2cc was 7168b8b, checked in by smk78, 10 years ago

Changed initial clean up to also include folders under
sphinx-docs/source/user as otherwise the pre-build copy was generating
multiple copies of files and causing Sphinx to throw many, many,
warnings.

  • Property mode set to 100644
File size: 3.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
13
14from distutils.dir_util import copy_tree
15from distutils.util import get_platform
16
17platform = '.%s-%s'%(get_platform(),sys.version[:3])
18
19CURRENT_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
20
21run = imp.load_source('run', os.path.join(CURRENT_SCRIPT_DIR, '..', '..', 'run.py'))
22run.prepare()
23
24SASVIEW_SRC = os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "src")
25SASVIEW_BUILD = os.path.abspath(os.path.join(CURRENT_SCRIPT_DIR, "..", "..", "build", "lib"+platform))
26SASVIEW_DOCS = os.path.join(SASVIEW_BUILD, "doc")
27
28SPHINX_BUILD = os.path.join(CURRENT_SCRIPT_DIR, "build")
29SPHINX_SOURCE = os.path.join(CURRENT_SCRIPT_DIR, "source")
30SPHINX_SOURCE_API = os.path.join(SPHINX_SOURCE, "dev", "api")
31SPHINX_SOURCE_GUIFRAME = os.path.join(SPHINX_SOURCE, "user", "guiframe")
32SPHINX_SOURCE_MODELS = os.path.join(SPHINX_SOURCE, "user", "models")
33SPHINX_SOURCE_PERSPECTIVES = os.path.join(SPHINX_SOURCE, "user", "perspectives")
34
35def _remove_dir(dir_path):
36    """Removes the given directory."""
37    if os.path.isdir(dir_path):
38        print "Removing \"%s\"... " % dir_path
39        shutil.rmtree(dir_path)
40
41def clean():
42    """
43    Clean the sphinx build directory.
44    """
45    print "=== Cleaning Sphinx Build ==="
46    _remove_dir(SASVIEW_DOCS)
47    _remove_dir(SPHINX_BUILD)
48    _remove_dir(SPHINX_SOURCE_GUIFRAME)
49    _remove_dir(SPHINX_SOURCE_MODELS)
50    _remove_dir(SPHINX_SOURCE_PERSPECTIVES)
51
52def retrieve_user_docs():
53    """
54    Copies across the contents of any media/ directories in src/, and puts them
55    in an appropriately named directory of docs/sphinx-docs/source/. For
56    example:
57
58        sas/../[MODULE]/media/dir/A.rst
59        sas/../[MODULE]/media/B.rst
60
61    gets copied to a new location:
62
63        docs/sphinx-docs/source/user/[MODULE]/dir/A.rst
64        docs/sphinx-docs/source/user/[MODULE]/B.rst
65
66    so that Sphinx may pick it up when generating the documentation.
67    """
68    print "=== Retrieve User Docs ==="
69
70    # Copy documentation files from their "source" to their "destination".
71    for root, dirnames, _ in os.walk(SASVIEW_SRC):
72        for dirname in fnmatch.filter(dirnames, 'media'):
73
74            docs = os.path.abspath(os.path.join(root, dirname))
75            print "Found docs folder at \"%s\"." % docs
76
77            dest_dir_part = os.path.dirname(os.path.relpath(docs, SASVIEW_SRC))
78            if os.sep in dest_dir_part:
79                dest_dir_part = dest_dir_part[dest_dir_part.index(os.sep) + 1:]
80            dest_dir = os.path.join(SPHINX_SOURCE, "user", dest_dir_part)
81
82            copy_tree(docs, dest_dir)
83
84def apidoc():
85    """
86    Runs sphinx-apidoc to generate .rst files from the docstrings in .py files
87    in the SasView build directory.
88    """
89    print "=== Generate API Rest Files ==="
90
91    # Clean directory before generating a new version.
92    _remove_dir(SPHINX_SOURCE_API)
93
94    subprocess.call(["sphinx-apidoc",
95                     "-o", SPHINX_SOURCE_API, # Output dir.
96                     "-d", "8", # Max depth of TOC.
97                     SASVIEW_BUILD])
98
99def build():
100    """
101    Runs sphinx-build.  Reads in all .rst files and spits out the final html.
102    """
103    print "=== Build HTML Docs from Rest Files ==="
104    subprocess.call(["sphinx-build",
105                     "-b", "html", # Builder name. TODO: accept as arg to setup.py.
106                     "-d", os.path.join(SPHINX_BUILD, "doctrees"),
107                     SPHINX_SOURCE,
108                     os.path.join(SPHINX_BUILD, "html")])
109
110    print "=== Copy HTML Docs to Build Directory ==="
111    html = os.path.join(SPHINX_BUILD, "html")
112    copy_tree(html, SASVIEW_DOCS)
113
114if __name__ == "__main__":
115    clean()
116    retrieve_user_docs()
117    apidoc()
118    build()
119       
120    print "=== Done ==="
Note: See TracBrowser for help on using the repository browser.