Skip to content

Instantly share code, notes, and snippets.

@ramnathv
Created March 28, 2012 16:02
Show Gist options
  • Save ramnathv/2227738 to your computer and use it in GitHub Desktop.
Save ramnathv/2227738 to your computer and use it in GitHub Desktop.
Hosting Sphinx Documentation on Github

This script has been adapted from a post on LA Times

from fabric.api import *
from fabric.contrib.console import confirm
def create_sphinx_pages():
"""
Create a new branch with Sphinx documentation ready to be published
using GitHub's Pages system.
Example usage:
$ fab make_sphinx_branch
Before you can publish your docs, you need to commit them to the repo.
$ git add .
$ git commit -am "First commit"
Then publish the files by pushing them up to GitHub.
$ git push origin gh-pages
Then the docs will appear on GitHub at:
http://<your_account_name>.github.com/<your_repo_name>/
"""
# CREATE CLEAN GH-PAGES BRANCH AND CHECK IT OUT
local("git branch gh-pages") # create the new branch
local("git checkout gh-pages") # move into it
local("git symbolic-ref HEAD refs/heads/gh-pages") # clear it out
local("rm .git/index")
local("git clean -fdx")
# INSTALL SPHINX AND SETUP PROJECT
local("pip install sphinx") # install sphinx
local("pip freeze > requirements.txt") # save dependencies
local("sphinx-quickstart") # start sphinx project
local("touch .nojekyll") # create .nojekyll file
# PATCH SPHINX MAKEFILE
local("echo '' >> Makefile")
local("echo 'BUILDDIR = ./' >> Makefile")
local("echo '' >> Makefile")
local("echo 'html:' >> Makefile")
local("echo '\t$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)' >> Makefile")
local("echo '\t@echo' >> Makefile")
local("echo '\t@echo \"Build finished. The HTML pages are in $(BUILDDIR)\"' >> Makefile")
# MAKE THE BRANCH FOR FIRST TIME
local("make html")
@ramnathv
Copy link
Author

I can insert the commands required to convert *_knit_.rst files to *.rst source files inside the part where the makefile is being patched.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment