How to document Python code using Doxygen

Question

I like Doxygen to create documentation of C or PHP code  I have an upcoming Python project and I think I remember that Python doesn t have          comments  and also has its own self-documentation facility which seems to be the pythonic way to document  Since I m familiar with Doxygen  how can I use it to produce my Python documentation  Is there anything in particular that I need to be aware of

User · Answer

An other very good documentation tool is sphinx. It will be used for the upcoming python 2.6 documentation and is used by django and a lot of other python projects.

From the sphinx website:

Output formats: HTML (including Windows HTML Help) and LaTeX, for printable PDF versions
Extensive cross-references: semantic markup and automatic links for functions, classes, glossary terms and similar pieces of information
Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
Automatic indices: general index as well as a module index
Code handling: automatic highlighting using the Pygments highlighter
Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules, and more

User · Answer

Sphinx is mainly a tool for formatting docs written independently from the source code  as I understand it   For generating API docs from Python docstrings  the leading tools are pdoc and pydoctor  Here s pydoctor s generated API docs for Twisted and Bazaar   Of course  if you just want to have a look at the docstrings while you re working on stuff  there s the  pydoc  command line tool and as well as the help   function available in the interactive interpreter

User · Answer

This is documented on the doxygen website  but to summarize here   You can use doxygen to document your Python code  You can either use the Python documentation string syntax       package docstring Documentation for this module   More details       def func           Documentation for a function       More details              pass   In which case the comments will be extracted by doxygen  but you won t be able to use any of the special doxygen commands   Or you can  similar to C-style languages under doxygen  double up the comment marker     on the first line before the member       package pyexample    Documentation for this module       More details      Documentation for a function       More details  def func        pass   In that case  you can use the special doxygen commands  There s no particular Python output mode  but you can apparently improve the results by setting OPTMIZE OUTPUT JAVA to YES   Honestly  I m a little surprised at the difference - it seems like once doxygen can detect the comments in    blocks or     blocks  most of the work would be done and you d be able to use the special commands in either case  Maybe they expect people using     to adhere to more Pythonic documentation practices and that would interfere with the special doxygen commands

User · Answer

In the end  you only have two options   You generate your content using Doxygen  or you generate your content using Sphinx     Doxygen  It is not the tool of choice for most Python projects  But if you have to deal with other related projects written in C or C   it could make sense  For this you can improve the integration between Doxygen and Python using doxypypy  Sphinx  The defacto tool for documenting a Python project  You have three options here  manual  semi-automatic  stub generation  and fully automatic  Doxygen like      For manual API documentation you have Sphinx autodoc  This is great to write a user guide with embedded API generated elements  For semi-automatic you have Sphinx autosummary  You can either setup your build system to call sphinx-autogen or setup your Sphinx with the autosummary generate config  You will require to setup a page with the autosummaries  and then manually edit the pages  You have options  but my experience with this approach is that it requires way too much configuration  and at the end even after creating new templates  I found bugs and the impossibility to determine exactly what was exposed as public API and what not  My opinion is this tool is good for stub generation that will require manual editing  and nothing more  Is like a shortcut to end up in manual  Fully automatic  This have been criticized many times and for long we didn t have a good fully automatic Python API generator integrated with Sphinx until AutoAPI came  which is a new kid in the block  This is by far the best for automatic API generation in Python  note  shameless self-promotion      There are other options to note    Breathe  this started as a very good idea  and makes sense when you work with several related project in other languages that use Doxygen  The idea is to use Doxygen XML output and feed it to Sphinx to generate your API  So  you can keep all the goodness of Doxygen and unify the documentation system in Sphinx  Awesome in theory  Now  in practice  the last time I checked the project wasn t ready for production  pydoctor   Very particular  Generates its own output  It has some basic integration with Sphinx  and some nice features

User · Answer

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

[python] How to document Python code using Doxygen

Examples related to python

Examples related to documentation

Examples related to python-sphinx

Examples related to doxygen

Examples related to docstring