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
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!
we have a github pages plugin that you can use:
in the below example we always build the static website but we only publish to github pages on push (when you merge a pull request it triggers a github push webhook).
- name: build
- npm install
- npm run build
- name: publish
the above example uses hard coded credentials for demo purposes only. you will want to use secrets to pass sensitive data to the plugin, and in this case, you may want to use an ssh key instead of username and password (see plugin docs).
Wow, I worked way too hard on this . Thanks for the answer @bradrydzewski. This works perfectly and is exactly what I wanted.
Here’s the gist of what I’m doing - minus some specific things to our use case.
- pip install -r requirements-test.pip
- make test
- make docs
- name: publish
This uses the defaults. My docs are sphinx and are located in
/docs/src. They are generated in /docs. My
.gitignore has (among other things)
make docs command runs my sphinx build. Then the static stuff is automatically pushed to
gh-pages as per the defaults of the plugin. My site is published from that branch. Hopefully that helps someone else.