source: sasview/docs/sphinx-docs/build_sphinx.py @ 35bf493

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 35bf493 was 35bf493, checked in by smk78, 9 years ago

Remove spurious indentation

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