Help
cancel
Showing results for 
Search instead for 
Did you mean: 
Highlighted
Ground Controller Lvl 1
Message 1 of 1

Understanding GitHub Pages deployment of generated documentation

I'd like to deploy my generated documentation files (primarily html) to GitHub Pages. I have an (open source) organization with multiple members and a few repositories at https://connectivecpp.github.io (and obviously https://github.com/connectivecpp/).

 

We have a large amount of annotated C++ code and are using Doxygen to generate HTML documentation from the source code. We are also using Travis for CI builds (and will also use GitHub actions in the future for our CI builds).

 

Since we are an organization we can't use the "gh-pages" branch for automatic deployment of the generated code. My understanding is that we can only use the "master" branch to render our GitHub pages at our .io address.

 

Question 1: I don't want to "git push" the many generated files to our master branch, at least in our source code repositories. Besides cluttering up git logs, it requires first deleting everything out of the documentation directory before pushing the new generated files back into the doc directory (or putting in place some sort of "diff between old and new set of generated files, delete unneeded old files, push new ones" script). Is there a better process?

 

Question 2: Related to 1, I'd be ok with pushing all generated files to our ".io" repository, which would keep our source code repositories clean of all generated doc files. It does complicate our documentation organization and the Doxygen generation step significantly, specially when putting it into some sort of deployment script (and we would still need the "diff" script). Is this what other organizations are doing?

 

Question 3: I've looked at third-party web sites that host documentation (such as Read the Docs at https://readthedocs.org), but each one has some drawbacks. I would rather use GitHub Pages. Should I reconsider a third-party web site?

 

Question 4: Am I missing something obvious? Is there a way to deploy to GitHub Pages without actually "git push"ing to a branch somewhere? I understand the Jekyll static site generation process (at a very high level), but IIUC I still need to push the doc files before the Jekyll (or other static web site generation) process kicks in.

 

I'm generating nice documentation (through CMake and Doxygen) locally, so I know the documentation generation works well. I'd rather not have to upload these files every time we create a new release, though, and would much rather automate the process through GitHub (and Travis, as needed). I've been searching online for weeks, but still don't have the understanding or directions that I need (most of the online help is oriented towards "gh-pages" workflows).

 

I greatly appreciate any and all comments and help.

 

Cliff