CODEWITHSUNDEEP
gitgithubgithub-pages
aaronrussell
aaronrussell

Reputation: 9467

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

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?

Upvotes: 20

Views: 6973

Answers (3)

paul-g
paul-g

Reputation: 3877

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.

Upvotes: 1

aaronrussell
aaronrussell

Reputation: 9467

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!

Upvotes: 16

Adam Dymitruk
Adam Dymitruk

Reputation: 129526

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

Upvotes: 0

Related Questions