Sphinx is the primary documentation tooling for most of my projects. I use it for the Linux command line book too. Last Friday while in a chat with Leif about documenting all of our puppet codebase, I thought of mixing these too.

Now puppet already has a tool to generate documentation from it's code, called puppet strings. We can use that to generate markdown output and then use the same in sphix for the final HTML output.

I am using https://github.com/simp/pupmod-simp-simplib as the example puppet code as it comes with good amount of reference documentation.

Install puppet strings and the dependencies

$ gem install yard puppet-strings

Then cloning puppet codebase.

$ git clone https://github.com/simp/pupmod-simp-simplib

Finally generating the initial markdown output.

$ puppet strings generate --format markdown --out simplib.md
Files                     161
Modules                   3 (3 undocumented)
Classes                   0 (0 undocumented)
Constants                 0 (0 undocumented)
Attributes                0 (0 undocumented)
Methods                   5 (0 undocumented)
Puppet Tasks              0 (0 undocumented)
Puppet Types              7 (0 undocumented)
Puppet Providers          8 (0 undocumented)
Puppet Plans              0 (0 undocumented)
Puppet Classes            2 (0 undocumented)
Puppet Data Type Aliases  73 (0 undocumented)
Puppet Defined Types      1 (0 undocumented)
Puppet Data Types         0 (0 undocumented)
Puppet Functions          68 (0 undocumented)
 98.20% documented

sphinx setup

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install sphinx myst_parser

After that create a standard sphinx project or use your existing one, and update the conf.py with the following.

extensions = ["myst_parser"]
source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'markdown',
    '.md': 'markdown',
}

Then copy over the generated markdown from the previous step and use sed command to update the title of the document to something better.

$ sed -i '1 s/^.*$/SIMPLIB Documenation/' simplib.md

Don't forget to add the simplib.md file to your index.rst and then build the HTML documentation.

$ make html

We can still improve the markdown generated by the puppet strings command, have to figure out simpler ways to do that part.

So we saw benefits of having documentation in the last post . In this post I will go through another topic we discuss a lot, code comments or not!

Let us look into a more common thing first. Look at the handwriting below and think if you have to read some notes/answer sheet/ideas, which side of the text you want it to be like? Left or Right?

Text from left hand side, you can read and understand. What about the right hand side text? Do you really want to read a 10 page long document in that handwriting? Now use the same ideas into the code you read regularly. People read a piece of code a many times than you think. (Btw, the right hand side was my own handwriting few months back.)

If you can not read your code without comments that means you are surely doing it in a wrong way, it is just bad code. You can think about comments as the extra toppings on top of your regular pizza, but it can not become your regular pizza (i.e. your code). Think about a world where comments do not exist, you have to name your variables right, refactor the code till it becomes obvious so that others can read and understand. Remember the Zen of Python

Simple is better than complex.

-- Zen of Python

Also remember that the comments are for human reader, they are not for the interpreters or compliers. There are many cases where a long comment will confuse the reader more than helping. This brings in another favorite quote.

to write good comments you have to be a good writer.

-- Jeff Atwood

But you may still want to have comments for other reasons. Let us look into some of those cases.

• I want to track all changes in the code. Sorry, wrong place, VCS/SCM exists for that particular reason. Use nicer commit messages so that later when you read back your log history, you will thank yourself.
• I want to use this commented code in future. Once again, you can get that back from your VCS/SCM. You don't want it lying around inside your code. Just remove it and keep the code clean.
• Reading English is easier than my programming language. We are programmers, we can understand code much better than anyone else.
• To find a piece of code. You can use any modern text editor (vim, emacs or sublimetext) and find symbols, classes very fast. Just learn to use your editor properly or choose a better one.
• What about TODO entries? This still makes sense while you are developing, but remember not to add a chapter of a book there.

Let us now look into a proper code comment example. Below are the lines from io.py in CPython.

# Declaring ABCs in C is tricky so we do it here.
# Method descriptions and default implementations are inherited from the C
# version however.
class IOBase(_io._IOBase, metaclass=abc.ABCMeta):
    pass

Now you can clearly see that there is no easy of saying that ABCs are tricky through your code, so the authors chose two simple English statements to explain it all.

The last point to discuss is about having comments or name variables in your code in your mother tongue (other than English). Bad idea, you really don't know the future. The next person who will read your code might be from another part of the world, English is the standard language for all of the programmers, try to follow the same path.

Please share your thoughts on the same as comments here or reply on twitter. In the next post I will look into docstrings in Python code.

documentation == communication

Yes, it is the primary medium to communicate to you users. You may have an API service or an installable library or an application, but your documentation quality matters when you think about retaining old users and getting new one!

Above is an old sketchnote I did, happiness of the users matters most and it can only come with providing a superb documentation along with your application/API.

Documentation comes in different forms, for the users first thing is a quickstart docs, something which can tried within 5-10 minutes, then comes tutorials and how-to guides, which can vary from 30 minutes to couple of hours to complete. API documentation comes after that, mostly for your experienced users, in-depth details and examples should be part of it.

There are many projects who will not accept a patch without the necessary documentation changes along with it. If you look into projects like Django or Qt , you will understand why they have such big userbase. Along with the excellent product, they provided world class documentation. There is another point which these projects teach, who should write the initial documentation?

Developers should write the initial documentation!

You read correct, not any new contributors but the developers themselves. As a developer, you already have better idea of the project and how it works, if you write the initial documentation that will help more for new contributors than them trying to find out how things work and then write the docs.

In next part I will discuss more on code comments.