How to create Github pages from a project's documentation?

Question

I have a project on Github that has a directory containing some automatically generated HTML documentation. I would like to use that documentation within Github's project pages facility.

So, I've read the instructions on how to create the project's gh-pages root branch. This effectively creates an empty branch.

What I'd like help with is mirroring the html files in the /docs path from the master branch, so they are in the root of the gh-pages branch. What is the best way of approaching this?

Answer 1

Answering my own question here... have achieved what I wanted with Git submodules.

I basically copied what's detailed in this sake task, but in summary:

• Moved the docs path into a temp folder. Commit changes.
• Created a clean gh-pages branch as per the usual instructions
• Moved everything from the temp folder into the new gh-pages branch. Commit changes.
• Back in the master branch, add the remote gh-pages as a submodule in the docs folder.
• Commit changes. Voila!

Answer 2

Mhm, I ended up writing these two Makefile targets to push my docs. I just do make update-doc and it generally works.

TMP_PATH="/tmp/some_path"

## the dir containing HTML docs to push to gh-pages
HTML_DIR="html"

## arbitrary dirs created by the doc build system that should be removed
TRASH=latex

update-doc: doc
        rm -rf ${TMP_PATH} && cp ${HTML_DIR} ${TMP_PATH} -R && rm -rf ${HTML_DIR}
        git fetch
        git checkout gh-pages
        cp ${TMP_PATH}/* . -R
        rm -rf ${TRASH}
        git add .
        git commit -m "Update documentation"
        git push -u origin gh-pages
        rm -rf ${TMP_PATH}
        git checkout master

# command to build documentation; can be customised but
# remember to also change the HTML_DIR and TRASH variables
doc:
        doxygen docs/doxygen.conf

.PHONY: doc update-doc

I use doxygen but you could change this to whatever other documentation system.

This assumes the gh-pages branch exists on the remote and was created as explained here.