Sphinx + github with no submodules

Previously, I detailed how I was using git submodules and gh-pages at github to host the html versions of my documentation generated by sphinx. Basically, the problem is that using git submodules for this is a real pain (for me, at least). You've always got to remember to sync up the submodule(s) just so, or things go horribly wrong and stop tracking each other.

Because I can never remember the correct order of what needs to be committed when, I searched for other ways. And searched. And searched. Finally, I ginned up something that I think I like. It basically uses a directory, within your project but ignored by .gitignore, to keep track of your gh-pages content. Because the .git directory tracks what you need to track, you can run make html for sphinx with impunity, and you can push your changes to gh-pages when you want - no need to remember what goes when and where.

Finally, you can track the raw rst of your doc files in the regular source tree, just like you should.

comments powered by Disqus