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