If you’ve been around at all recently, you’ve probably noticed how much I talk about my current project: Sample Programs in Every Language. Well, today isn’t any different because we just began automating the Sample Programs Wiki.
Table of Contents
The Sample Programs Wiki
If you’ve explored the Sample Programs repository
, you may have stumbled upon its wiki. If not, the wiki is basically the repository’s documentation. Of course, it’s much more than that. It’s a tool for language exploration and data analytics.
Since starting this project, I’ve gotten a lot of community support. In fact, the project currently has 54 stars and 23 forks which I think is amazing. On top of that, one of the project’s biggest contributors, Alcha, is the reason that the wiki exists.
After all, Alcha came up with the idea of using the wiki to help deal with some of my content management concerns. Since then, they built up most of the wiki you see today by hand. Don’t believe me? Check the revision history!
Once I saw the finished version, I knew I wanted more. For instance, I’m interested in seeing all the languages in the repository organized by year of release. Unfortunately, this creates a situation where we have duplicate data floating around which isn’t ideal.
As a result, I took it upon myself to automate the wiki building before even knowing if it was possible. In a future article, I’ll break down how I automated the wiki exactly. In the meantime, I’ll give a brief overview.
How the Automation Works
In general, the automation works in two parts:
- A Python Script
- A Travis CI Build
As you can probably imagine, the python script sits alongside the Sample Programs repository and analyzes the collection directly. In other words, we can use the directory structure as a clue when building up the various wiki pages.
At a high level, the Python script reads in all kinds of data like language names, number of scripts, and size of scripts. With that data, the script then generates a set of wiki files in markdown. If you’re interested in that script, it’s called generator.py.
Unfortunately, the Python script alone isn’t really automation. While it does build the wiki pages, I would still have to push those files to the wiki. That’s where the Travis CI build comes in.
At a high level, the Travis CI builds works by triggering a build every time a commit to master is made. During the build, the Python script is executed. Once we have our wiki files, we clone the wiki, update the necessary wiki files, and push the changes.
Obviously, all of this was easier said than done. The Python script alone took me a few days as did the Travis CI build. Overall, I spent probably 4-5 days on the project, and now we have a fully automated wiki.
Future Options
As of right now, I’m very happy with the automation. Of course, there are a few kinks. In particular, I’m not able to easily access GitHub information which I would like to use to populate some of the wiki pages. In addition, it may be easier to generate a dynamic documentation in some other way.
As a result, we’re looking at potentially changing the way we handle our documentation in the future. In fact, we already have a few ideas:
- Leverage GitHub Pages
- Build a Probot
From what I understand, we could use GitHub pages instead of the wiki to handle some of our dynamic information. For instance, we could create tables that could be sorted by different kinds of information. In other words, I could get my alphabetical table and my chronological table in one go.
As another option, we’re considering making a Probot which is essentially a bot with repository privileges. In other words, we could develop a Probot which could do exactly what I’ve setup already. In all likelihood, Probots probably make it easier to do everything I did, and I’m sure it would be easier to maintain.
At any rate, thanks for sticking around. If any of this sounds interesting, consider forking the repository. We love the help! While you’re here, why not subscribe to The Renegade Coder? That way, you can give feedback below.
Recent Posts
Teaching at the collegiate level is a wonderful experience, but it's not always clear what's involved or how you get there. As a result, I figured I'd take a moment today to dump all my knowledge for...
It's been a weird week. I'm at the end of my degree program, but it's hard to celebrate. Let's talk about it.