Sphinx

For a long time, creating documentation has been a pain in the ass for me. It’s so tedious and boring as hell. Even though I know that the one who will need them the most in the future is ME! But boring job is still boring, no matter what you coated them with. It’s against all my aesthetic as a programmer.

I used to avoid them like a plague by saying that’s a job of System Analyst. That’s true, right? That’s what I learn in the school.

But recently in the rise of agile methodology, it seems the distinction between the traditional hierarchy is blurring. Not to mention that I usually works as a single super programmer.

I know about Sphinx since a long time ago, but works and hobbies got in the way. Well, my laziness had more impact. At first I try using Wiki page in the Version Control. But it’s not sit quite well with me. You have to read them in the version control website for one. I also stumble across MkDocs. It’s easier and simpler. But due to the simplicity nature, MkDocs didn’t have a lot of advance feature as Sphinx. It’s fine if you need a simpler documentation. At this point I give up and try Sphinx. Boy, how it impress me.

Sphinx is harder to learn than MkDocs, yes. But the hard work pay off in the end. As a programmer I like it because in Sphinx, there’s almost no distinction than coding.

You can even generate graphic and UML diagram in Sphinx. Though sadly the Database Diagram is rather poor. Because it’s heavily designed for Japanese due to the font it use. And I don’t quite like the syntax. But you may like this Sphinx ERDiagram.

Note

After some times, I decide to create them myself because I really need it.

You can see it here.

On Windows

Recently I realize that when working in open source world, it’s much easier to use Linux than Windows. And after learning about Docker, I try using it as much as possible due to the reason above. But since I use Windows 7, it’s a little hassle due to Docker Toolbox limitation. sphinx-autobuild didn’t work in Docker on Windows!

After some times I got fed-up and try Windows 10. But Sphinx auto build still didn’t work on Docker here too. Hell, what’s the point in migrating from 7 to 10 I thought. But because I’ve already move on anyway, let’s use Windows 10 anyway.

Because sphinx-autobuild is still refused to works, I give up and try using the good old virtualenv. So far so good, if you ignore the ANSI color code. But I got tired fast. It’s so hard to read with all those garbage (color code)!

I also try using bash to activate the ANSI color that comes with GIT. But due to the nix nature, I feel like a tourist. Not to mention that you cannot run some Windows executable here.

There must be a better way!

—Raymond Hettinger (Python Core Developer)

He’s one of my favorite Python guru. That’s his favorite saying lately. So I do some research and found a lot of console alternatives. It’s so many that I’m speechless.

After two days of research and try every console alternative out there, I found that cmder is simply the best. You can see more info about cmder in Console article.

PDF Adventure

Generating to HTML is great. And they so easy to boot. You can even host them to Read the Docs freely. But sometimes you need the PDF for one reason or the other.

It’s quite easy in linux machine. After installing some package, you can simply run make pdflatex and it’s magically done! Though you may have a hard time if you want to use xelatex instead. But here I am lost in Windows dessert.

Note

Latex option in conf.py seems to have latex_engine entry. See here. Should try this later in linux machine.

First of all, I don’t even know how to compile tex file to pdf. After some research I found out about MiKTeX. Best of all, MiKTeX have portable version. Yes!

After some tinkering in MiKTeX, I finally able to create pdf file successfully. Hooray!!!

Kanji Hell

After some pleasant time in Sphinx, I need to insert kanji character in my document. Trust me, I never expected it to be so hard! And yet after some uselessly struggling days, the solutions is so absurdly simple!

Reading countless article about Sphinx and Latex. I realize that unicode really is a serious business. No wonder Python took so much time to migrate to unicode.

It took me days to finally arrive to this article. After trying the solution by editing the tex file produced by Sphinx directly, I found that the solution works! One obstacle down. Next problem is how to bring the solution to Sphinx.

The answer is of course by creating extension is Sphinx, right? Easier said than done. So I set out on a new adventure to Sphinx extension world. For one week I’m lost in the Sphinx and reStructuredText world. Until finally I’m able to create the extension. Another obstacle down! Now, let’s upload the extension to PyPI.

Seriously, I never imagine that the time will come where I need to upload my package to PyPI. Usually they already sitting there. So I learn about PyPI for two days and finally able to upload to PyPI. Then I’m able to download my package from PyPI. Well, it’s quite easy compared to when I create Sphinx extension I must say.

I’m so happy for many reasons. Until I make a little mistake when using the extension. It’s just a small typo! But to my great astonishment, the kanji character in the wrong role nonchalantly appears in the PDF file!

Wait the minutes…

So I try typing the kanji character without the role. And it’s appears perfectly!

WHAT THE $%@*!

Even though in the past they appear as tofu or blank in the PDF file! I’m sure of that!

After some trial and error, I found out that I only need the “correct” latex preamble in conf.py file. In the past, the preamble is not the one I use now. Though I already forgot what.

LATEX_PREAMBLE = r'''
\usepackage{xeCJK}
\setCJKmainfont{MS Mincho}
\setCJKsansfont{MS Gothic}
'''

latex_elements = {
    ...
    'preamble': LATEX_PREAMBLE,
    ...
}

Then you can compile the tex file using xelatex:

> xelatex pdf.tex

That’s IT!

Quirks

All files and sub folders of _static folder will be copied as is to build, but html_favicon and html_logo file will always be copied to _static root folder in build folder if you put them in the sub folder.

And Beyond…

Recently I always try to create my documents in reStructuredText format. It’s all nice and warm if you only need the soft copy. Things become a little complicated when I need to print them. After some little googling I decide to use RestView. The only qualm is I don’t like the default style. Fortunately, we can use our own style. So I created my own style.