docs.py 1.8 KB
Newer Older
1
from __future__ import print_function
Will Daly committed
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
import sys
from paver.easy import *


DOC_PATHS = {
    "dev": "docs/en_us/developers",
    "author": "docs/en_us/course_authors",
    "data": "docs/en_us/data",
    "default": "docs/en_us"
}


def valid_doc_types():
    """
    Return a comma-separated string of valid doc types.
    """
    return ", ".join(DOC_PATHS.keys())


def doc_path(options, allow_default=True):
    """
    Parse `options` (from the Paver task args) to determine the path
    to the documentation directory.
    If the specified path is not one of the valid options, print an error
    message and exit.

    If `allow_default` is False, then require that a type is specified,
    and exit with an error message if it isn't.
    """
    doc_type = getattr(options, 'type', 'default')
    path = DOC_PATHS.get(doc_type)

    if doc_type == 'default' and not allow_default:
35 36 37 38 39 40
        print(
            "You must specify a documentation type using '--type'.  "
            "Valid options are: {options}".format(
                options=valid_doc_types()
            )
        )
Will Daly committed
41 42 43
        sys.exit(1)

    if path is None:
44 45 46 47 48 49
        print(
            "Invalid documentation type '{doc_type}'.  "
            "Valid options are: {options}".format(
                doc_type=doc_type, options=valid_doc_types()
            )
        )
Will Daly committed
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
        sys.exit(1)

    else:
        return path


@task
@needs('pavelib.prereqs.install_prereqs')
@cmdopts([
    ("type=", "t", "Type of docs to compile"),
    ("verbose", "v", "Display verbose output"),
])
def build_docs(options):
    """
    Invoke sphinx 'make build' to generate docs.
    """
    verbose = getattr(options, 'verbose', False)

    cmd = "cd {dir}; make html quiet={quiet}".format(
        dir=doc_path(options),
        quiet="false" if verbose else "true"
    )

    sh(cmd)