How to publish docs that are already built elsewhere?

I already auto-generate the static HTML docs for my project as part of a build pipeline (which is currently hosted in Azure DevOps). Is it possible for me to simply auto-deploy my static content as-is into a GitHub Pages website?

Ideally different versions of the docs would be accessible: one version for each stable release of my project, but also one showing the docs for the latest pipeline build (and which could therefore have ‘broken’ docs). Is this use case supported by GitHub Pages?


Hey @cacti77! GitHub Pages is a static site generator and suited very well for this use case. The one caveat is that you can only deploy one instance of GitHub Pages from the repo so you will need to build some sort of infrastructure into your HTML content such that you can access the different docs for the different releases. 


Ok thanks - you mean somehow support the different versions directly within the docs tree itself? That makes sense, although I’m not sure how I’d achieve that in my particular situation.

I also had an online chat with GitHub Pages support about this issue.  They said “You can deploy [the static docs] from the docs folder, gh-pages branch, or the root of the master branch.”  But the important point about my situation is that the static HTML is not currently committed anywhere. The static HTML is generated automatically as part of the build process itself (by sphinx, which generates API docs from specially formatted comments in the Python source code).

So it sounds like I’d need to create a separate repo just for my static docs and update this repo automatically as part of my build pipeline. In other words, delete all the static docs from the previous build and then commit all the newly generated static docs from the current build.  Is this what you are suggesting?

I suppose I could create one repo for each version of the docs too, maybe (yuck - ideally they’d just be on different release tags of the same repo).

1 Like

In the end I created a project repo just to host the docs. Under /docs folder I added a folder for each stable release and then added the static HTML docs for each corresponding release version. I also had to add an empty .nojekyll file to the docs folder to ensure the Sphinx docs were rendered properly, as per Bypassing Jekyll on GitHub Pages - The GitHub Blog.