Package: ghp-import
GitHub Pages ImportAs part ofgunicorn,Benoit ChesneauandPaul Daviswere looking at how to host documentation. There's the obvious method of
usingGitHub's post-receive hookto trigger doc builds and rsync
to a webserver, but we ended up wanting to try out github's hosting to make the
whole interface a bit more robust.GitHub Pagesis a pretty awesome service that GitHub provides for
hosting project documentation. The only thing is that it requires agh-pagesbranch that is the site's document root. This means that keeping
documentation sources in the branch with code is a bit difficult. And it really
turns into a head scratcher for things likeSphinxthat want to
access documentation sources and code sources at the same time.Then we stumbled across an interesting looking package calledgithub-toolsthat looked almost like what we wanted. It was a tad
complicated and more involved than we wanted but it gave us an idea. Why not
just write a script that can copy a directory to thegh-pagesbranch of the
repository. This saves us from even having to think about the branch and
everything becomes magical.This is whatghp-importwas written for.Big Fat WarningThis willDESTROYyourgh-pagesbranch. If you love it, you'll want to
take backups before playing with this. This script assumes thatgh-pagesis
100% derivative. You should never edit files in yourgh-pagesbranch by hand
if you're using this script because you will lose your work.When used with a prefix, only files below the set prefix will be destroyed, limiting the
above warning to just that directory and everything below it.UsageUsage: ghp-import [OPTIONS] DIRECTORY

Options:
  -n, --no-jekyll       Include a .nojekyll file in the branch.
  -c CNAME, --cname=CNAME
                        Write a CNAME file with the given CNAME.
  -m MESG, --message=MESG
                        The commit message to use on the target branch.
  -p, --push            Push the branch to origin/{branch} after committing.
  -x PREFIX, --prefix=PREFIX
                        The prefix to add to each file that gets pushed to the
                        remote. Only files below this prefix will be cleared
                        out. [none]
  -f, --force           Force the push to the repository.
  -o, --no-history      Force new commit without parent history.
  -r REMOTE, --remote=REMOTE
                        The name of the remote to push to. [origin]
  -b BRANCH, --branch=BRANCH
                        Name of the branch to write to. [gh-pages]
  -s, --shell           Use the shell when invoking Git. [False]
  -l, --follow-links    Follow symlinks when adding files. [False]
  -h, --help            show this help message and exitIts pretty simple. Inside your repository just runghp-import $DOCS_DIRwhere$DOCS_DIRis the path to thebuiltdocumentation. This will write a
commit to yourgh-pagesbranch with the current documents in it.If you specify-pit will also attempt to push thegh-pagesbranch to
GitHub. By default it'll just rungit push origin gh-pages. You can specify
a different remote using the-rflag.The-ooption will discard any previous history and ensure that only a
single commit is always pushed to thegh-pagesbranch. This is useful to
avoid bloating the repository size and ishighly recommended.You can specify a different branch with-b. This is useful for user and
organization page, which are served from themasterbranch.Some Windows users report needing to pass Git commands through the shell which can be accomplished by passing-s.The-loption will cause the import to follow symlinks for users that have odd configurations that include symlinking outside of their documentation directory.Python UsageYou can also call ghp_import directly from your Python code as a library. The
library has one public functionghp_import.ghp_import, which accepts the
following arguments:srcdir: The path to thebuiltdocumentation (required).remote: The name of the remote to push to. Default:origin.branch: Name of the branch to write to. Default:gh-pages.mesg: The commit message to use on the target branch. Default:Update documentation.push: Push the branch to {remote}/{branch} after committing. Default:False.prefix: The prefix to add to each file that gets pushed to the remote. Default:None.force: Force the push to the repository. Default:False.no_history: Force new commit without parent history. Default:False.use_shell: Default: Use the shell when invoking Git.False.followlinks: Follow symlinks when adding files. Default:False.cname: Write a CNAME file with the given CNAME. Default:None.nojekyll: Include a .nojekyll file in the branch. Default:False.With Python's current working directory (cwd) inside your repository, do the
following:fromghp_importimportghp_importghp_import('docs',push=True,cname='example.com')