Automatically publish Tinkerer bld output to GitHub with Travis CI

Perface

I saw a comment from a web that talks about auto deployment with Travis CI

As an aside, you can also use GitHub Pages for hosting, which is free, and then integrate it with Travis-CI to automatically publish the blog (basically run pelican to generate the output and push the changes back online) in order to decouple the actual writing of blog posts from the publishing part.

The above also has the advantage of enabling a history of changes done (both for the articles themselves and the output), as well as simplifying things if you want to have guest posts and so on.

That's the place where I start to explore Travis CI.

Travis CI

Travis CI part isn't hard to figure out. I referenced the following articles to get me started with this great tool, particularly with Sphinx-doc:

learn-travis

Sphinx-doc repo .travis.yml

Have Travis-CI test your Sphinx docs

The basic idea of Travis CI is quite simple. Once you commit something, it will trigger Travis CI to clone your repository, and run the command you specified in .travis.yml and then it will tell you the result of this commit (i.e. Whether you pass all the test specified in .travis.yml)

Work with Tinkerer

Note

Tinkerer is built upon Sphinx-doc. Any Sphinx-doc-ish tool should have similar setup when work with Travis CI.

The setup for me is that I don't use gh-pages. Instead, I directly use master branch as the source for my github page. The reason is that Tinkerer will generate index.html directly inside root directory of the repo, which will redirect the visit to index.html under blog. blog is the default output directory.

Here are the tutorials I referenced. However, all of them talk about working with gh-pages:

Auto-deploying built products to gh-pages with Travis

Automatically Publish Javadoc to GitHub Pages with Travis CI

The first link above offers a framework of how you should get everything working and the second link's bottom script offers some intuition.

I'm not going to redo the work. I just want to point out something you need to be careful:

DO NOT use personal token. As mentioned by the first link, using a GitHub personal access token offers the full access to all your git repo. That's a very high risk.
Be Careful with Public/Private. You need to use the Travis client to encrypt the private ssh key and upload the corresponding public ssh key to your repository.
Don't put passphrase for your ssh key. If you do, Travis CI will ask for the passphrase during the automation process, which will lead to build hang. If this happens, regenerate the ssh key.
Be careful only upload your .enc file. Don't upload your ssh private key to your repo.

Decode the script

.travis.yml

This is my .travis.yml:

language: python
python:
  - "2.7"

install:
  - pip install tinkerer
  - pip install sphinxjp.themes.tinkerturquoise

script:
  - tinker -b

env:
  global:
  - ENCRYPTION_LABEL: "8c1ec1f6b778"
  - COMMIT_AUTHOR_EMAIL: "[email protected]"

after_success:
  - bash ./deploy.sh

notifications:
  email:
    recipients:
      - [email protected]
    on_success: change # option [alway|never|change]
    on_failure: always

install section asks Travis CI to install the necessary packages to build our doc.
script section contains our doc build command.
env section contains environment variables required for our deploy.sh. They are used to authorize a user on Travis CI to make git clone, git push, etc.
after_success tells Travis CI what to do once the script section is done successfully.
notifications customize the email notification.

deploy.sh

For deploy.sh is easy to understand if you take a look at the Travis CI log for a build.

Travis CI first perform basic the environment setup. Then, it clones the git repository. Next, it builds our doc. If the build is success, it executes our deploy.sh.

Inside deploy.sh, the main idea is to first clone the same repo (i.e. travis-dup) and copy the bld output pages (under /xxks-kkk/blog/blog) to the bld directory of the same repo we just cloned (i.e. travis-dup/blog). If there is nothing changed in the bld output pages, we exit. Else, we commit the changes and use the authencation we just added (i.e. ssh-add travis) and push the change to the repo.

To keep it simpler, you can imagine Travis CI is a remote server that you can do anything you want. Thus, we can let bld result to be pushed to our repo by asking user (i.e. travis) from the remote server to do so.