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?

See [my related answer](http://stackoverflow.com/a/29616287/946850) and a [writeup](http://krlmlr.github.io/git-subbranch) for an alternative. — krlmlr, Apr 13 '15 at 22:53
Possible duplicate of [git branch: gh-pages](http://stackoverflow.com/questions/4750520/git-branch-gh-pages) — Dan Dascalescu, Aug 18 '16 at 17:49
Hey @Martijn Pieters, I'm fine with you deleting my post once the question is closed as a dupe. So far, this one hasn't. — Dan Dascalescu, Aug 19 '16 at 21:45

score 16 · Accepted Answer · answered Jun 15 '11 at 11:32

16

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!

answered Jun 15 '11 at 11:32

aaronrussell

9,389
5
38
62

6

Do you have to then `cd` into the `docs` folder and commit/push everything separately or is there a way to do so with a single command from the root? – Rob Fletcher Sep 02 '11 at 02:08
Do you have to pull each update to `gh-pages` into your submodule with this approach? Does it work well in practice? – krlmlr Apr 13 '15 at 22:54

score 1 · Answer 2 · answered Nov 05 '15 at 18:18

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.

score 0 · Answer 3 · answered Jun 15 '11 at 02:48

0

create symlinks for those files to that spot. You should be able to commit those too.

answered Jun 15 '11 at 02:48

Adam Dymitruk

124,556
26
146
141

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

3 Answers3

Linked