Sphinx in particular together with rdt theme is a great tool to create documentation.
Github pages are great to host documentation. This post is about one option to use those two technologies together.
Sphinx documentation that should contain .nojekyll files can be built locally e.g.:
sphinx-build -b html . _build
In order to serve the generated content on github pages the content of the _build directory must be uploaded to a github repository.
Basically the _build folder content has to be part of a gh-pages branch on a github repository.
To automate that I created the sphinx to gh pages converter bash script.
The documentation https://lotharschulz.github.io/sphinx-pages/ is generated as an example with the sphinx contents of https://github.com/lotharschulz/sphinx-pages using the sphinx to gh pages converter bash script.
Please note the preconditions and install notes in order to use sphinx to gh pages converter bash script properly.
These are the steps the script performes:
- make sure the master branch is clean:
https://github.com/lotharschulz/sphinx-pages/blob/master/sphinx-2-gh-pages-converter.sh#L8-L13 - create html based on sphinx source files:
https://github.com/lotharschulz/sphinx-pages/blob/master/sphinx-2-gh-pages-converter.sh#L16 - create or use an existing gh-pages branch:
https://github.com/lotharschulz/sphinx-pages/blob/master/sphinx-2-gh-pages-converter.sh#L19-L29 - use the generated html files and push to remote gh-pages branch:
https://github.com/lotharschulz/sphinx-pages/blob/master/sphinx-2-gh-pages-converter.sh#L31-L42
Leave a Reply