# -*- coding: utf-8 -*-
"""paved.sphinx -- helpers and tasks for Sphinx documentation.
"""
from paver.easy import task, needs, sh, path, options, Bunch

from . import paved
from . import util

util.update(
    options.paved,
    dict(
        docs = Bunch(
            path = path('./docs'),
            targets = ['html'],
            build_rel = '_build/html',
            upload_location = False,
            ),
        )
    )

__all__ = ['sphinx_make', 'docs', 'clean_docs', 'rsync_docs']


def sphinx_make(*targets):
    """Call the Sphinx Makefile with the specified targets.

    `options.paved.docs.path`: the path to the Sphinx folder (where the Makefile resides).
    """
    sh('make %s' % ' '.join(targets), cwd=options.paved.docs.path)


@task
def docs():
    """Make Sphinx docs.

    `options.paved.docs.path`: the path to the Sphinx folder (where the Makefile resides).

    `options.paved.docs.targets`: the Make targets to send to `sphinx_make`. Default is `html`.
    """
    sphinx_make(*options.paved.docs.targets)


@task
def clean_docs():
    """Clean Sphinx docs.

    `options.paved.docs.path`: the path to the Sphinx folder (where the Makefile resides).
    """
    sphinx_make('clean')


@task
@needs('docs')
def rsync_docs():
    """Upload the docs to a remote location via rsync.

    `options.paved.docs.rsync_location`: the target location to rsync files to.
    
    `options.paved.docs.path`: the path to the Sphinx folder (where the Makefile resides).

    `options.paved.docs.build_rel`: the path of the documentation
        build folder, relative to `options.paved.docs.path`.
    """
    assert options.paved.docs.rsync_location, "Please specify an rsync location in options.paved.docs.rsync_location."
    sh('rsync -ravz %s/ %s/' % (path(options.paved.docs.path) / options.paved.docs.build_rel, 
                                options.paved.docs.rsync_location))

@@ -84,16 +84,42 @@
 on.%0A%22%22%22%0A
+from . import paved, util%0A
 from pav
@@ -174,48 +174,23 @@
 unch
-%0A%0Afrom . import paved%0Afrom . import util
+, BuildFailure%0A
 %0A%0Aut
@@ -486,16 +486,27 @@
 nc_docs'
+, 'ghpages'
 %5D%0A%0A%0Adef 
@@ -1910,8 +1910,1514 @@
 ation))%0A
+%0A@task%0Adef ghpages():%0A    '''Push Sphinx docs to github_ gh-pages branch.%0A    %0A     1. Create file .nojekyll%0A     2. Push the branch to origin/gh-pages %0A        after committing using ghp-import_%0A    %0A    Requirements:%0A     - easy_install ghp-import%0A%0A    Options:%0A     - %60options.paved.docs.*%60 is not used%0A     - %60options.sphinx.docroot%60 is used (default=docs)%0A     - %60options.sphinx.builddir%60 is used (default=.build)%0A     %0A    .. warning::%0A        This will DESTROY your gh-pages branch. %0A        If you love it, you'll want to take backups %0A        before playing with this. This script assumes %0A        that gh-pages is 100%25 derivative. You should %0A        never edit files in your gh-pages branch by hand %0A        if you're using this script because you will %0A        lose your work.%0A     %0A    .. _github: https://github.com %0A    .. _ghp-import: https://github.com/davisp/ghp-import %0A    '''%0A    %0A    # copy from paver%0A    opts = options%0A    docroot = path(opts.get('docroot', 'docs'))%0A    if not docroot.exists():%0A        raise BuildFailure(%22Sphinx documentation root (%25s) does not exist.%22%0A                           %25 docroot)%0A    builddir = docroot / opts.get(%22builddir%22, %22.build%22)%0A    # end of copy%0A    %0A    builddir=builddir / 'html'%0A    if not builddir.exists():%0A        raise BuildFailure(%22Sphinx build directory (%25s) does not exist.%22%0A                           %25 builddir)%0A    %0A    nojekyll = path(builddir) / '.nojekyll'%0A    nojekyll.touch()%0A    %0A    sh('ghp-import -p %25s' %25 (builddir))%0A    %0A

new task: ghpages