We have several repositories that contain code and documentation. The docs are generated with sphinx from code and sometimes some additional markdown or rst is added.
What we’d like to happen:
- User writes code/tests/comments/docs
- User opens a pull request
- Pull request is reviewed, changes pushed, and ultimately it’s merged
- Merging should kick off a new pipeline to generate documentation
- Docs are generated and published to github pages
How we get the docs to GH Pages isn’t set in stone.
Right now what I was trying to do was to have my pipeline trigger builds when a pull request is opened
trigger: event: - pull_request branch: exclude: - drone_docs
Then my pipeline would run the generation and open a new PR from the drone_docs branch to the master branch. GH pages was pulling from the
docs folder. This caused an awful loop where drone started trigger both the push and pr on drone_docs and continually building them one after the other and adding many commits to my drone_docs branch. I had to delete the branch and kill the builds several times before it stopped. This is obviously my fault and not Drone’s. I gave it some bad configuration.
Does anyone else build docs in their pipelines and publish them to github pages? There are other ways to handle docs. I could build the HTML and put it on the gh-pages branch, for example. Then maybe exclude all builds from that branch except the ones for docs?
Any examples, workflows, or ideas would be great!