The doxypy input filter allows you to use pretty much all of Doxygen’s formatting tags in a standard Python docstring format. I use it to document a large mixed C++ and Python game application framework, and it’s working well.
You’re not the only one! There was a discussion on comp.lang.python about this a while ago, and a recipe was created. Check it out here. “”” doc_inherit decorator Usage: class Foo(object): def foo(self): “Frobber” pass class Bar(Foo): @doc_inherit def foo(self): pass Now, Bar.foo.__doc__ == Bar().foo.__doc__ == Foo.foo.__doc__ == “Frobber” “”” from functools import wraps class … Read more
To avoid confusion: the term property has a specific meaning in python. What you’re talking about is what we call class attributes. Since they are always acted upon through their class, I find that it makes sense to document them within the class’ doc string. Something like this: class Albatross(object): “””A bird with a flight … Read more
It is nice for a Python module to have a docstring, explaining what the module does, what it provides, examples of how to use the classes. This is different from the comments that you often see at the beginning of a file giving the copyright and license information, which IMO should not go in the … Read more
Have a look at the reStructuredText (also known as “reST”) format, which is a plaintext/docstring markup format, and probably the most popular in the Python world. And you should certainly look at Sphinx, a tool to generate documentation from reStructuredText (used for eg. the Python documentation itself). Sphinx includes the possibility to extract documentation from … Read more
Python does not have such a mechanism. Prepend a # to each line to block comment. For more information see PEP 8. Most Python IDEs support a mechanism to do the block-commenting-with-hash-signs automatically for you. For example, in IDLE on my machine, it’s Alt+3 and Alt+4. Don’t use triple-quotes; as you discovered, this is for … Read more
Formats Python docstrings can be written following several formats as the other posts showed. However the default Sphinx docstring format was not mentioned and is based on reStructuredText (reST). You can get some information about the main formats in this blog post. Note that the reST is recommended by the PEP 287 There follows the … Read more