pdiazvargas
commented
5 years ago Process has been automated by adding the following to the Makefile:
gh-pages:
git checkout gh-pages
rm -rf _images _sources _static
git checkout master docs examples assets
$(MAKE) -C docs html
mv -fv docs/_build/html/* ./
rm -rf docs examples assets
git add -A
git commit -m "Generated gh-pages" && git push origin gh-pages; git checkout master
What
Right now juniper is using sphinx for documentation purposes. Updating the docs and previewing the changes locally is a straight forward process. However! once a PR makes documentation changes, getting those changes to go live by publishing or moving the doc changes to the
gh-pagesbranch is not a straightforward process.Ideally, this should be part of the circle.ci pipeline. This way whenever a PR is merged to master, the docs step could build the documentation and push the artifacts to the
gh-pagesbranch. The process could also be part of theMakefile.How
This could be a combination of a command in the Makefile that will be included as part of the circleci pipeline. Or it could be a completely independent build job in which the docs are built and deployed to the appropriate branch.
Right now this is a manual process which is not a scalable solution in the long run.
Why
Being able to streamline a process like the build and update of documentation will help us make less mistakes and will encourage a more proactive update of the documentation.