Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Sphinx documentation to github gh-pages without submodules
# assume the following directory structure where contents of doc/
# and source/ are already checked into repo., with the exception
# of the _build directory (i,e. you can check in _themes or _sources
# or whatever else).
#
# proj/
# source/
# doc/
# remove doc/_build/html if present
cd doc && rm -rf doc/_build/html
# edit .gitignore to ignore _build
echo "_build" >> .gitignore
git add .gitignore
git commit -m 'ignoring _build'
#create a new directory (in doc/)
mkdir -p _build/html
# clone the entire repo into this directory (yes, this duplicates it)
git clone git@github.com:username/project.git _build/html
# set this directory to track gh-pages
git symbolic-ref HEAD refs/heads/gh-pages
rm .git/index
git clean -fdx
# in docs/, run `make html` to generate our doc, which will fill
# _build/html, but not overwrite the .git directory
make html
# now, add these bad-boys to the gh-pages repo, along with .nojekyll:
cd _build/html
touch .nojekyll
git add .
git commit -m 'first docs to gh-pages'
git push origin gh-pages
# [optional] cleanup stuff in duplicate master (in docs/_build/html)
git co master
rm .git/index
git clean -fdx
# now, when you run `make html` and need to update your documentation,
# you can do it "normally" without worrying about the many vagaries of
# submodule syncing (I can never get the order correct). just make
# changes, then:
make html
cd _build/html
git commit -a -m 'made some changes, yo'
git push origin gh-pages
@denis-bz
Copy link

denis-bz commented Mar 8, 2013

Brant, would you have a simplified version of this with /proj/doc only ?
Along the lines

local == remote proj/... with proj/doc empty

# init a new repo in doc/ with branch gh-pages --
cd doc
git init
git branch --orphan gh-pages
git add remote origin git@github.com:myname/proj.git

# make index.html, push it --
make index.html
git add index.html
git commit -m "8mar index.html"
git push origin gh-pages  # -> remote proj/doc/index.html ??
# browse to myname.github.com/proj/doc

Thanks, cheers
-- denis

@jilljenn
Copy link

jilljenn commented Oct 27, 2018

There is a typo above: git checkout --orphan gh-pages

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