Embedded Files
Sphinx - A Python documentation generator
Sphinx - A Python documentation generator
Sphinx is a great bit of software that make documenting your python code easy. It can read standard comment styles to auto generate code documentation straight from your source files. It even lets you add reStructured text to add latex, code, images, maths and lengthier descriptions to you documents making for clear and complete explanations of you software. Finally, you can output you documents in multiple formats including latex, pdf and html, perfect for uploading to a server or GitHub Pages to support your code out in the wild.
For more information on seting up and using sphinx:
Tutorial: Sphinx
Website: https://www.sphinx-doc.org/en/master/
Quick start guide: https://www.sphinx-doc.org/en/master/usage/quickstart.html
Style is Eternal
Style is Eternal
As Yves Saint Laurent said "Fashion fades, but style is eternal". With a correct and consistent style your code comments can be eternal too. Comments can help now but mean nothing in three months when you've forgotten why you wrote that function even if you do know its iterating over the list in pairs. With a formal style you can keep those and add a layer of thought to your code that will make it clearer the whys as well as the hows.
Comment styles allow us to add documentation in the code file itself which tells us for different parts:
Why did we make it?
What is it supposed to be used for?
What do I input?
What will it output?
What could go wrong?
There are, as one might expect, as many different code commenting styles as stars in the sky. Here we are going to focus on a short list of 4.
Numpy docstrings
Google docstrings
reStructured text
Eyptext
More here
Page updated
Report abuse