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

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 f620870 was f620870, checked in by Peter Parker, 9 years ago

Allow deeply nested media directories to have their paths properly preserved on copy.

  • Property mode set to 100644
File size: 3.4 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_part = os.path.dirname(os.path.relpath(docs, SASVIEW_SRC))
68            if os.sep in dest_dir_part:
69                dest_dir_part = dest_dir_part[dest_dir_part.index(os.sep) + 1:]
70            dest_dir = os.path.join(SPHINX_SOURCE, "user", dest_dir_part)
71
72            copy_tree(docs, dest_dir)
73
74def apidoc():
75    """
76    Runs sphinx-apidoc to generate .rst files from the docstrings in .py files
77    in the SasView build directory.
78    """
79    print "=== Generate API Rest Files ==="
80
81    # Clean directory before generating a new version.
82    _remove_dir(SPHINX_SOURCE_API)
83
84    subprocess.call(["sphinx-apidoc",
85                     "-o", SPHINX_SOURCE_API, # Output dir.
86                     "-d", "8", # Max depth of TOC.
87                     SASVIEW_BUILD])
88
89def build():
90    """
91    Runs sphinx-build.  Reads in all .rst files and spits out the final html.
92    """
93    print "=== Build HTML Docs from Rest Files ==="
94    subprocess.call(["sphinx-build",
95                     "-b", "html", # Builder name. TODO: accept as arg to setup.py.
96                     "-d", os.path.join(SPHINX_BUILD, "doctrees"),
97                     SPHINX_SOURCE,
98                     os.path.join(SPHINX_BUILD, "html")])
99
100    print "=== Copy HTML Docs to Build Directory ==="
101    html = os.path.join(SPHINX_BUILD, "html")
102    copy_tree(html, SASVIEW_DOCS)
103
104if __name__ == "__main__":
105    clean()
106    retrieve_user_docs()
107    apidoc()
108    build()
109       
110print "=== Done ==="
Note: See TracBrowser for help on using the repository browser.