3.7 Writing clear documentation strings with RST markup

How can we clearly document what a function does? Can we provide examples? Of course we can, and we really should. In the Including descriptions and documentation recipe in Chapter 2, and in the Writing better docstrings with RST markup recipe, we looked at some essential documentation techniques. Those recipes introduced ReStructuredText (RST) for module docstrings.

We’ll extend those techniques to write RST for function docstrings. When we use a tool such as Sphinx, the docstrings from our function will become elegant-looking documentation that describes what our function does.

3.7.1 Getting ready

In the Forcing keyword-only arguments with the * separator recipe, we looked at a function to compute wind-chill, given the temperature and wind-speed.

In the recipe, we’ll show several versions of the function with trailing _0 in the name. Pragmatically, this...