How to build your tutorial library

Around 2 months back, I was surfing the web looking for information on building recommender systems using SageMaker and found this. And I said, “wow! what an impressive way of presenting information in this step by step manner. I want the same one for my tutorials”. But how to get it? And what it is called? I tried googling but found nothing solid. I assigned a CRON job to my subconscious to remind me about this and resumed the work.

And since I am already using FastPages to share and maintain my tutorials library, the urge was strong but not too strong. Meanwhile experimented with documentation tools — Sphinx, MkDocs, and GitHub Wiki — to share and maintain my tutorials along with other relevant documents.

I found the name by then, of that ‘love at first sight’ tool. It is called Codelabs and was built by a team of googlers. And this time, I see lot of relevant content — because of the keyword ‘codelabs’ — this huge library and associated link to tools repo gave me enough content to try it out myself.

Initially followed this guideline and it worked great — used google docs to write and the shortcut link to view the tutorial. Then, I followed this tutorial to setup my environment in Unix, so that I can convert google docs to static site. I did, and placed the code in a folder inside my fastpages repo which was already hosted on gh-pages. In this way, I was able to easily host my codelabs tutorial on my gh-pages site.

Next, I wanted to automate the process, at least to some extent, so that when I want to add a new tutorial, I just follow a particular process to add the new tutorial to my gh-pages. But google docs didn’t feel friendly enough format to automate the process. So shifted to markdown format to write tutorials. I already use notion, which gives me ‘export as markdown’ option for feature-loaded docs. But dropped this idea and decided to use Jupyter notebooks to write tutorials.

And most importantly, I wanted to build a landing page also, just like this one. My codelabs were looking homeless without this homepage. Technically, the pipeline is like this now: notebook > nbconvert > markdown > claat > static site > tools repo > gulp serve > gulp dist > gh-pages.

It worked better than expected, and fully managed on cloud for free. No need to install any software. Check out this codelab to learn the steps.

But it was still a lengthy, manual and quite technical process. I wanted to automate it further. So I decided to use GitHub Actions to automate. I added the automation instructions in YAML format in .github > workflows > CI.yml file. Check the file here. Let’s quickly break it down and understand a bit because it kind of summarized the whole process in a neat and structured manner.

Line 1–7: Run this automation pipe whenever a push event happens on the master branch.

Line 9–12: Run a job named build-site on ubuntu machine and execute the following steps.

Line 13–14: Checkout the master branch into Github workspace.

Line 15–30: Install Claat and nbconvert toolkits to convert the Jupyter notebooks into static site codelabs.

Line 31–42: Convert notebooks into codelabs by first copying all linked images into codelabs folder. Then use run nbconvert on notebooks in a loop to convert notebooks into markdown files and then run claat export command to convert these markdowns into codelabs static site files.

Line 43–57: These are some patches to correct the paths of static site files. It took me some time to figure out the right format of these patches and it might look complex if you are unfamiliar with ubuntu shell commands but don’t worry, let me know and I will cover these formats in-depth in future.

Line 58–66: Install node package manager. We need this package to execute gulp commands.

Line 67–80: Run the gulp dist command to build the whole site. And then apply the same path patch again to the whole site related files.

Line 81–86: Use the gh-pages toolkit to copy the site folder — stored in site > stage > dist folder — to gh-pages branch.

Check out this codelab tutorial to build a site for yourself.

In future, I will keep adding new features and enhancements to design and functionalities. For instance, currently automation pipe is taking 3–4 mins to run. We can try to bring it down to 30–40 sec with caching and other tricks.

Remarks: To contribute, please add features in branches and create pull request. Give the project a thumbs up if you found it useful.

My next goal in this line is to automate the whole documenting process so that I just place my docs and code in one location and my Sphinx, MkDocs, FastPages, and the lovely Codelabs, all got updated automatically.