Auto deploying Sphinx theme documentation using Travis CI
Hi everyone, Today I’m gonna share my experience in auto-deploying a documentation site to Github Pages using Travis CI.
This is how it began. I started contributing to “FOSSASIA” Organization on Google Code-in 2019 contest and there was a task related to the “ PSLab” (Pocket Science Lab) project. “PSLab: Improve Code Quality of PSLab Documentation Site” this was the task.
What is PSLab…? before anything I’ll explain what is PSLab briefly. PSLab is a small USB powered hardware extension for your Android phone or PC that lets you measure all kinds of things. PSLab comes with a built-in Oscilloscope, Multimeter, Wave Generator, Logic Analyzer, Power Source, and we are constantly adding more digital instruments.
Visit PSLab Official Site to learn more.
Visit FOSSASIA Official Site to learn more about their projects.
To start working on the task first I looked at the issues section on “PSLab documentation” repository and found an issue opened “Create Sphinx documentation in gh-pages branch” and I started working on it.
What is Sphinx…? Sphinx is a tool written by python which mostly used to generate documentation from “.rst” (reStructuredtext files).
To learn about their theme visit sphinx-themes
I had the repository already cloned into my local files. First, need to set up a virtual environment to learn about virtual environments visit Python Virtual Environments, and then I installed sphinx to my local repository. In my case, I used sphinx-material theme.
Need to know how to install sphinx-material theme? visit Material for Sphinx
After the installation, you would see a “conf.py” file created in your local repository do the required changes according to your project. You can get a clear idea by visiting Material for Sphinx.
Since the .rst (reStructuredtext) file was already created by someone before, it saved time. To learn how to write a “.rst” file visit Learn reStructuredtext.
So after that, all I had to do is auto-deploy the site to the gh-pages branch in every merge. For that, I used Travis CI.
What is Travis…? Travis CI is a hosted continuous integration service used to build and test software projects hosted at GitHub and Bitbucket.
Visit Travis Official site to learn more.
To build the project using Travis first we need to create a file “travis.yml” on the repository. The “travis.yml” is a YAML format text file. This file specifies the programming language used, dependencies that must be installed before the software can be built and tested. In my case, I have to include the programming language as “Python” and the commands used to install sphinx-material and the “upload-gh-pages.sh” to deploy the site automatically to the gh-pages branch.
Then I set some environmental variables on the “upload-gh-pages.sh” and in Travis repository settings like $USER_NAME, $GITHUB_API_KEY, because after the Travis build is successful, to auto-deploy Travis needs access to the -user Github repository.
And the final result was a beautiful and neat documentation site, and also I did some customizations on the theme like changing the colour to red. You also can customize the theme, to learn it visit Customize sphinx material.
Check out the result: https://kumuditha-udayanga.github.io/pslab-documentation/
PSLab documentation: https://docs.pslab.io/
PR Link: https://github.com/fossasia/pslab-documentation/pull/80
From this blog post, you can get an idea about auto-deploying sphinx themed documentation using Travis CI. Hope this helped you.
Thank you for reading…!
