3 Different Docstring Formats for Python | by Yash Salvi | Apr, 2022

A fast walkaround of Google, NumPy, and Sphinx docstrings

Photograph by wu yi on Unsplash

Python is turning into a well-liked programming language these days. For any coding challenge, documentation is an important half for rising the readability of code however on the similar time most overlooked half too! To resolve this, the Sphinx software turns out to be useful which automates the documentation half, for those who aren’t conscious of this software, take a look at this.

Now that you just’re conscious of Sphinx and know use it. Tell us essentially the most generally used docstring codecs on the market within the wild, that are namely- Google, NumPy, and Sphinx docstring codecs.

This docstring format is really helpful by Khan Academy and is popularly generally known as “Google Docstring”. To verify the docstring is suitable with Sphinx and is acknowledged by Sphinx’s autodoc, add the sphinx.ext.napoleon extension within the conf.py file. The docstring format is:

The output generated by Sphinx appears like this:

The output in HTML file

To make life simpler for those who’re utilizing VS Code, you’ll be able to set up this extension. This extension lays the boilerplate for the docstrings and also you solely want so as to add the outline of every parameter.

This documentation format is utilized in main information science libraries like NumPy, SciPy, and Pandas. Identical to Google’s docstring, to make it suitable with Sphinx you’ve so as to add the sphinx.ext.napoleon extension within the conf.py file. The format for docstring is:

The output for a similar is:

The output in HTML file

Google Vs NumPy’s Docstrings:

The output for each docstrings appears related, the primary distinction between the 2 types is that Google makes use of indentation to separate sections, whereas NumPy makes use of underlines. NumPy fashion tends to require extra vertical area, whereas Google-style tends to make use of extra horizontal area. Google-style tends to be simpler to learn for brief and easy docstrings, whereas NumPy-style tends to be simpler to learn for lengthy and in-depth docstrings.

Nothing higher than the great outdated sphinx docstring, that is essentially the most fundamental docstring format that’s used however is considerably visually dense which makes it laborious to learn. The format for a similar is:

The output appears like this:

The output of HTML FIle

To experiment with the completely different codecs, clone this repository. As soon as cloned, mess around with the codecs and run themake clear html adopted by make htmlinside docs folder to regenerate the HTML recordsdata.

Apart from the above codecs, there are numerous docstring codecs that can be utilized for Python and we don’t have a single winner on this sport.

So select whichever format you’re comfy with, don’t combine the codecs, and keep it up all through the challenge. My private favourite is NumPy’s Docstring!

More Posts