<p>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 <code>/* .. */</code> comments, and also has its own self-documentation facility which seems to be the pythonic way to document.</p>
<p>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?</p>

[{'answer_id': 58701, 'author': 'Blair Conrad', 'author_id': 1199, 'author_profile': 'https://Stackoverflow.com/users/1199', 'pm_score': 7, 'selected': True, 'text': '<p>This is <a href="http://www.doxygen.nl/manual/docblocks.html#pythonblocks" rel="noreferrer">documented on the doxygen website</a>, but to summarize here:</p>\n\n<p>You can use doxygen to document your Python code. You can either use the Python documentation string syntax:</p>\n\n<pre><code>"""@package docstring\nDocumentation for this module.\n\nMore details.\n"""\n\ndef func():\n    """Documentation for a function.\n\n    More details.\n    """\n    pass\n</code></pre>\n\n<p>In which case the comments will be extracted by doxygen, but you won\'t be able to use any of the <a href="http://www.doxygen.nl/manual/commands.html#cmd_intro" rel="noreferrer">special doxygen commands</a>.</p>\n\n<p><strong>Or</strong> you can (similar to C-style languages under doxygen) double up the comment marker (<code>#</code>) on the first line before the member:</p>\n\n<pre><code>## @package pyexample\n#  Documentation for this module.\n#\n#  More details.\n\n## Documentation for a function.\n#\n#  More details.\ndef func():\n    pass\n</code></pre>\n\n<p>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 <code>OPTMIZE_OUTPUT_JAVA</code> to <code>YES</code>.</p>\n\n<p>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?</p>\n'}, {'answer_id': 59018, 'author': 'Peter Hoffmann', 'author_id': 720, 'author_profile': 'https://Stackoverflow.com/users/720', 'pm_score': 4, 'selected': False, 'text': '<p>An other very good documentation tool is <a href="http://www.sphinx-doc.org/en/master/index.html" rel="nofollow noreferrer">sphinx</a>. It will be used for the upcoming python 2.6 <a href="http://docs.python.org/dev/" rel="nofollow noreferrer">documentation</a> and is used by <a href="http://docs.djangoproject.com/en/dev/" rel="nofollow noreferrer">django</a> and a lot of other python projects.</p>\n\n<p>From the sphinx website:</p>\n\n<ul>\n<li><strong>Output formats</strong>: HTML (including Windows HTML Help) and LaTeX, for printable PDF versions</li>\n<li><strong>Extensive cross-references</strong>: semantic markup and automatic links for functions, classes, glossary terms and similar pieces of information</li>\n<li><strong>Hierarchical structure</strong>: easy definition of a document tree, with automatic links to siblings, parents and children</li>\n<li><strong>Automatic indices</strong>: general index as well as a module index</li>\n<li><strong>Code handling</strong>: automatic highlighting using the Pygments highlighter</li>\n<li><strong>Extensions</strong>: automatic testing of code snippets, inclusion of docstrings from Python modules, and more</li>\n</ul>\n'}, {'answer_id': 59955, 'author': 'Allen', 'author_id': 6043, 'author_profile': 'https://Stackoverflow.com/users/6043', 'pm_score': 5, 'selected': False, 'text': '<p>Sphinx is mainly a tool for formatting docs written independently from the source code, as I understand it.</p>\n\n<p>For generating API docs from Python docstrings, the leading tools are <a href="https://github.com/BurntSushi/pdoc" rel="noreferrer">pdoc</a> and <a href="https://launchpad.net/pydoctor" rel="noreferrer">pydoctor</a>. Here\'s pydoctor\'s generated API docs for <a href="http://twistedmatrix.com/documents/current/api" rel="noreferrer">Twisted</a> and <a href="http://starship.python.net/crew/mwh/bzrlibapi/" rel="noreferrer">Bazaar</a>.</p>\n\n<p>Of course, if you just want to have a look at the docstrings while you\'re working on stuff, there\'s the "<a href="https://docs.python.org/2/library/pydoc.html" rel="noreferrer">pydoc</a>" command line tool and as well as the <code>help()</code> function available in the interactive interpreter.</p>\n'}, {'answer_id': 497322, 'author': 'Community', 'author_id': -1, 'author_profile': 'https://Stackoverflow.com/users/-1', 'pm_score': 7, 'selected': False, 'text': '<p>The <a href="https://pypi.python.org/pypi/doxypy/" rel="noreferrer">doxypy</a> 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.</p>\n'}, {'answer_id': 35377654, 'author': 'Havok', 'author_id': 439494, 'author_profile': 'https://Stackoverflow.com/users/439494', 'pm_score': 5, 'selected': False, 'text': '<p>In the end, you only have two options:</p>\n\n<p>You generate your content using Doxygen, or you generate your content using Sphinx*.</p>\n\n<ol>\n<li><p><strong>Doxygen</strong>: 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 <a href="https://github.com/Feneric/doxypypy" rel="noreferrer">doxypypy</a>.</p></li>\n<li><p><strong>Sphinx</strong>: The defacto tool for documenting a Python project. You have three options here: manual, semi-automatic (stub generation) and fully automatic (Doxygen like). </p>\n\n<ol>\n<li>For manual API documentation you have Sphinx <a href="http://www.sphinx-doc.org/en/stable/ext/autodoc.html" rel="noreferrer">autodoc</a>. This is great to write a user guide with embedded API generated elements.</li>\n<li>For semi-automatic you have Sphinx <a href="http://www.sphinx-doc.org/en/stable/ext/autosummary.html" rel="noreferrer">autosummary</a>. You can either setup your build system to call sphinx-autogen or setup your Sphinx with the <code>autosummary_generate</code> 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.</li>\n<li>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 <a href="http://autoapi.readthedocs.org/" rel="noreferrer">AutoAPI</a> 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).</li>\n</ol></li>\n</ol>\n\n<p>There are other options to note:</p>\n\n<ul>\n<li><a href="https://breathe.readthedocs.org/" rel="noreferrer">Breathe</a>: 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.</li>\n<li><a href="https://github.com/twisted/pydoctor" rel="noreferrer">pydoctor</a>*: Very particular. Generates its own output. It has some basic integration with Sphinx, and some nice features.</li>\n</ul>\n'}]
['https://Stackoverflow.com/questions/58622', 'https://Stackoverflow.com', 'https://Stackoverflow.com/users/2077/']