Because I choose to.

# Write a Diary with Sphinx

My favorite lightweight markup language is reStructuredText [1]. Unlike XML/HTML, a lightweight markup language is more human-readable, while it still preserves some basic abilities of expressing hyper-text content. This article (and also the blog) is written in reStructuredText. Though not as famous as Markdown [2], reStructuredText, in my opinion, is more feature-rich and extensible. The official Python document [3] is written in it, with the help of Sphinx [4], the documentation generator, powered by the lower-level reST engine, docutils [5].

Usually documentation generators are used by code projects to generate accompanied references and tutorials. However, thanks to the versatility of Sphinx, we can also keep our personal diaries with it! Here I'm gonna show how one can keep multiple diaries at the same time via a single Sphinx project.

## Quickstart

First thing to do is to make sure sphinx is installed on your machine. In Archlinux, it is simply:

Then we can make use of the quick start tool to create a template documentation project:

This will start a wizard which asks several questions about the preference of your project. Suppose you mostly follow the default settings, the project directory diaries/ will end up like this:

>> cd diaries/
** 02:28:50 /t/diaries ymf@Pixelbook **
>> ls -l
total 16
drwxr-xr-x 2 ymf ymf   40 Jun 22 02:28 _build
-rw-r--r-- 1 ymf ymf 4723 Jun 22 02:28 conf.py
-rw-r--r-- 1 ymf ymf  449 Jun 22 02:28 index.rst
-rw-r--r-- 1 ymf ymf  607 Jun 22 02:28 Makefile
drwxr-xr-x 2 ymf ymf   40 Jun 22 02:28 _static
drwxr-xr-x 2 ymf ymf   40 Jun 22 02:28 _templates


Here, we can include our reST files in index.rst, each keeps track of one diary. In index.rst:

As you might have guessed, we should accordingly add two reST files life.rst and research.rst to our project directory. In life.rst:

In research.rst:

Finally, try to build your diaries:

This command shall generate HTML output to _build/html directory. Open the browser to see the compiled diaries: