Documenting code

There are currently three different documentation styles supported by Sphinx: the original Sphinx style and the more recent NumPy and Google styles. The differences between them are mainly in style, but it’s actually slightly more than that.

The Sphinx style was developed using a bunch of reStructuredText roles, a very effective method, but it can be detrimental for readability when used a lot. You can probably tell what the following does, but it’s not the nicest syntax:

:param number: The number of eggs to return
:type number: int

The Google style was (as the name suggests) developed by Google. The goal was to have a simple/readable format that works both as in-code documentation and is parseable for Sphinx. In my opinion, it comes closer to the original idea of reStructuredText, a format that’s very close to how you would document instinctively. This example has the same meaning as the Sphinx style example shown earlier...