Whereas PEP8 outlines coding conventions for Python, PEP257 standardises the excessive stage construction, semantics, and conventions of docstrings: what they need to comprise, and how you can say it in a transparent method. As with PEP8, these usually are not onerous guidelines, however they’re tips which you’d be clever to comply with.
If you happen to violate these conventions, the worst you’ll get is a few soiled seems to be.
So, what then is a docstring? A docstring is a string literal that happens as the primary assertion in a module, perform, class, or methodology definition. Such a docstring turns into the __doc__ particular attribute of that object. As with PEP8, I received’t copy and reformat the entire PEP, you need to flick through it in your individual time, however listed below are two examples of docstrings for features.
- Instance single line docstring for a perform add:
def add(a, b):
"""Sum two numbers."""
return a + b
2. Instance multi-line docstring for a perform complicated:
def complicated(actual=zero.zero, imag=zero.zero):
"""Type a fancy quantity.
Key phrase arguments:
actual -- the true half (default zero.zero)
imag -- the imaginary half (default zero.zero)
if imag == zero.zero and actual == zero.zero:
In spite of everything, your nicely formatted docstrings are in place, subsequent you’re going to wish to convert them into prettified undertaking documentation. The de-factor Python documentation generator known as Sphynx, and it could generate output like html, pdfs, unix man pages, and extra.
Right here’s a great tutorial on getting began with Sphynx. Briefly, after initialising Sphynx in some listing (sometimes your docs listing), and establishing its configuration, you’ll work in your reStructuredText (*.rst) information, which after calling make, will probably be transformed to your most popular output documentation sort.
As a enjoyable apart, you may create references to different components of your Python program straight out of your docstrings, which seem as hyperlinks within the output documentation.
As an instance output typical of Sphynx documentation generator, right here is an incomplete however bulging checklist of Python tasks with Sphynx generated documentation. Examples embrace matplotlib, networkX, Flask, and pandas.