Tom Ordonez

Data Science, Machine Learning, Growing Teams

From Markdown to Sphinx reStructuredText


For the last year I have been taking online courses in Coursera and reading books in programming and computer science.

What I usually do to keep track of learning is to create a directory for a topic and put all the materials there.

For instance when I took Python in Coursera I did this:

  • Created a directory
  • Added the course book
  • Created a venv
  • Added the code
  • Added a README file with my daily learning

README

I used the README file as my diary. The good thing about online learning is that you can watch the video material as many times as you want or pause it and play it.

I used books to support my learning. And used the README file in the same way that you would use a notebook to write my lesson.

I believe that if you write things down you learn more and you can go back to this material as a reminder.

Why I love markdown

I love Markdown because it is simple. Just as I love Vim.

For Vim I have a simple setup and I know a few simple commands.

I know how to exit a Vim file :)

This website uses markdown and I am writing in markdown right now.

But I never go back to the markdown source code to read my blog posts. All this content is pushed online. I consult all my blog posts online.

Learning README and Markdown

This has been a problem for learning and keeping a diary.

All those topics I have been studying are in README files in Markdown.

They turn out to be very long files and they are hard to read in Vim.

I have been looking for something better.

Readthedocs

I went to Pycon last year and met the founder of Readthedocs. I honestly had no idea what that was until the conference was over, did some homework and saw how much technical documentation was used for this.

That moment when you realize "I met the founder of X and I asked him what his (awesome_fill_in_the_blanks_technology) was about".

I saw that many Python projects use Readthedocs for documentation and for the following months I thought of reviewing how to learn this. But then I didn't.

Georgia Tech

I recently started at Georgia Tech and I am taking Computer Networks. I think a key to success is to be very organized.

I am using TaskWarrior for task management.

Following the same way to organize the files. I have a directory of courses and a README file.

For this class I have two. One for my diary and another one for the book.

Sphinx

I went back to readthedocs and found this blog post about why you shouldn't use Markdown. And realized "hey that's the guy I met".

I watched this screencast on how to get started with Sphinx and reStructuredText.

The video shows how to install Sphinx, a bit about reStructuredText and how to push to readthedocs.

One thing I have to be careful is that for my README file I have been adding a lot of code.

For my class. I cannot have any homework code out there in public.

I thought of having a private repo. But then I thought that my diary could help someone new taking the class.

I am in the process of doing this:

  • Install Sphinx
  • Add lessons learned and reference code only to the docs
  • Keep homework code outside of the docs
  • Push to Github/readthedocs diary/reference code only

With reference code I mean code that is from a libary official doc or public code and that is not related to a project or a specific solution for the class.

More details about this later.