4

I transferred a project from Google Code to Github. This project contained, in one directory structure, both code and documentation.

I'd like to use the "Pages" functionality of Github to host html documentation. Ideally, I'd like to do 1 push to commit changes to code & documentation.

How can I achieve this?

jldupont
  • 93,734
  • 56
  • 203
  • 318

1 Answers1

2

When it comes to GitHub pages, you have user pages and project pages.
I will suppose you are speaking of the latter, which means you need to create your own gh-pages branch, copy your documentation files from your master branch in this new empty branch, as described in the GitHub doc page.

From there, when you have new commits both in your master and gh-pages branches, you can push both branches in one push (git push --all)

The problems start when you absolutely want to see both directory structures at the same time.
The simplest solution is:

  • one clone of your repo set on the master branch.
  • one clone (of the same repo) on the gh-pages branches.
  • a symlink from the first repo to the second repo (which allows you to make modifications on code and doc in the same directory structure. Symlinks are even supported on Windows since Vista).
  • a git alias script in order to automate the command sequence 'git push master origin; cd ../secondRepo; git push gh-pages origin'

You can try to get a doc repo as a submodule of your main repo, but... that seems way more complex that it ought to: see "How to add a git repo as a submodule of itself? (Or: How to generate GitHub Pages programmatically?)".

Update August 2016: Simpler GitHub Pages publishing now allows to keep your page files in a subfolder of the same branch (no more gh-pages needed):

Now you can select a source in your repository settings and GitHub Pages will look for your content there.

You finally can update both code and pages in one branch.

Community
  • 1
  • 1
VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
  • +1: Not sure how to manage the "symlink" portion though... could you expand on this, please? – jldupont Nov 16 '11 at 20:48
  • @jldupont the idea is to have two separate clones, in two separate directory structures, but be able to see both from one of those clone. If you are on Windows, you can use `mklink` (http://www.windows7home.net/how-to-create-symbolic-link-in-windows-7/) to see one repo within another. And that is much easier than submodules in this case. – VonC Nov 16 '11 at 21:10
  • @jldupont and Von. I'm currently struggling with the same issues. This seems like a reasonable answer. After two years do you two like how it works or have you come up with something better? Thanks! – user949300 Oct 08 '13 at 20:48