How to build docs in one branch and automatically copy build/html into the gh-pages branch

Github stores project websites in in a seperate branch (gh-pages) of the project repository. We have in master a sphinx package that builds our docs and want to automatically commit the generated docs to the gh-pages branch.

Sphinx config and the source cannot be in the gh-pages branch themselves because that branch contains only html.If the master didnt' version the html it self, this would be see(use .git ignore as shown here How can I commit specific directory to a different than a working branch on git?). What happens if it is version.

I want to type make publish and have it build the docs ( we have this as a make targe开发者_StackOverflow社区t already) and then apply those changes to the gh-pages branch (forcibly in fact).

The problem is that gh-pages is effectively the contents of doc/build/html , so a standard merge would seem not to work.

stashing the changes,changing branches, and applying results in conflicts and there appears to be no way to specify a merge strategy of --ours.

Sub-tree merging and such techniques appear to be intended for merging external repositories, not things in the same repo.

---

I found these steps very useful for publishing to a different branch like gh-pages. There are some other scripts you can google, but this one seemed more clearly written.

Generally the steps are: - add your current outdir to .gitignore - clone whole repo to outdir to initiate .git there, clean it and make a gh-pages branch - make a build that you push from outdir.

You can follow the code that uses two separate folders for master and gh-pages here, the comments are in Russian, but commands are rather self-explanatory.

---

you can create a branch which is empty and where you can only commit your html's. just follow the github pages instructions for "Project Pages" from here.