Elegant theme for pelican has been undergoing a big change from individual-driven effort to community, as part of this, one of the tasks to accomplish, has been the decoupling from author blog to project site for documentation.
As we wanted this process to be both automated and allowed us to demonstrate via dogfooding that the theme works and how it looks, the idea was to automate the rendering of pelican website with new documents.
Under the hood¶
Setting an automated build required several steps to be done:
- Get a GitHub token that could be used by Travis for pushing to a repo (and configure it in Travis environment variables for the repo in a variable named
- run unit tests for validating new PR before merging
- configure Travis so that it downloads required dependencies in order to run pelican and then publish the generated web to the repo
- a GitHub pages enabled repo so that resulting files can be viewed as a webpage.
One of the key pieces is a properly configured
.travis.yaml like the one we started using:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
So, from above file we do:
1 2 3 4 5 6
- Configure language as python
- Select distribution
- Confirm we require ‘sudo’ access
- Configure python version as 3.5
All of this depends on Travis Image being used and their documentation
Preparation of environment¶
Now, we’ll prepare the environment for our tests:
1 2 3 4 5 6 7 8
We do install pip, setuptools, repository and test requirements, peru and tox.
Peru is used to grab additional dependencies for elegant (plugins, latest theme, etc)
This is really easy in our case:
1 2 3
We run ‘tox’ that allows to automate Python virtualenv and tests and then, use the Makefile from Pelican to build the site and tests plugins, etc
If everything succeeds, we’re ready for the next step (publishing)
After tests passed¶
All the environment setup and tests have succeed now, we do need to push the site ‘live’
1 2 3 4 5 6 7 8
This piece does the final step, first removes info about the repo containing the actual documentation and allows us to initialize a new one, that we make it point towards the repo we’re pushing (so that we keep separate actual website content from ‘rendered’ website).
In the final step, ‘make github’ uses the makefile provided with pelican to push the changes to the ‘master’ branch of the target repository, that then, is ready to be served via github pages as a regular web server would do.
So, right now we’ve accomplished several things:
- We do use pelican in the same way that we’ll do for our own website
- We do also have as a consequence, a ‘live’ demo of latest master branch showcasing features
- We did automate publishing of webpage as soon as contributors send new articles and are approved for merge
- All requires no extra change to regular workflow as
is the glue here puting together all the pieces.
Hope you enjoy it!