Differences between revisions 46 and 47
Revision 46 as of 2021-02-02 09:16:35
Size: 5206
Editor: MaxHils
Comment: Update pdoc entry. It would probably make sense to massively shorten both the pdoc and pdoc3 entires, but I'm not touching the latter due to partiality (see mailing list).
Revision 47 as of 2023-02-04 13:42:35
Size: 5261
Editor: GilOliveira
Comment: Updated outdated Sphinx links
Deletions are marked like this. Additions are marked like this.
Line 30: Line 30:
 * [[http://sphinx.pocoo.org/ext/autosummary.html|autosummary]], an extension for the Sphinx documentation tool.
 * [[http://sphinx.pocoo.org/ext/autodoc.html|autodoc]], a Sphinx-based processor that processes/allows reST doc strings.
 * [[https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html|autosummary]], an extension for the Sphinx documentation tool.
 * [[https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html|autodoc]], a Sphinx-based processor that processes/allows reST doc strings.
Line 52: Line 52:
 * [[Sphinx]], http://sphinx.pocoo.org/ - converts reStructuredText documentation into various formats  * [[Sphinx]], https://www.sphinx-doc.org/ - converts reStructuredText documentation into various formats

This page is primarily about tools that help, specifically, in generating documentation for software written in Python, i.e., tools that can use language-specific features to automate at least a part of the code documentation work for you. The last section also lists general documentation tools with no specific support for Python (though some of them are themselves written in Python).

Tools that support auto-documentation of code can be broadly classified into tools that:

  • import the code to generate documentation based on runtime introspection
  • parse and analyze the code statically (without running it)

See here for a longer explanation of the two concepts.

Tools that generate documentation from user-provided input typically use plain text markup formats such as reStructuredText (reST, the markup used for writing the official Python documentation) or Markdown.

Python docstrings

Python modules are usually documented using docstrings. You can read a module's docstrings from the Python interactive prompt with the help() function. For example:

import distutils
help(distutils)

The help() function uses Python's standard pydoc module, as does the pydoc command that comes with Python.

Automatic Python API documentation generation tools

  • autosummary, an extension for the Sphinx documentation tool.

  • autodoc, a Sphinx-based processor that processes/allows reST doc strings.

  • pdoc, a simple Python 3 command line tool and library to auto-generate API documentation for Python modules. Supports Numpydoc / Google-style docstrings, doctests, reST directives, PEP 484 type annotations, custom templates ...

  • pdoc3, a fork of pdoc for Python 3 with support for Numpydoc / Google-style docstrings, doctests, LaTeX math, reST directives, PEP 484 type annotations, custom templates ...

  • PyDoc, a documentation browser (in HTML) and/or an off-line reference manual. Also in the standard library as pydoc.

  • pydoctor, a replacement for now inactive Epydoc, born for the needs of Twisted project.

  • Doxygen can create documentation in various formats (HTML, LaTeX, PDF, ...) and you can include formulas in your documentation (great for technical/mathematical software). Together with Graphviz, it can create diagrams of your code (inhertance diagram, call graph, ...). Another benefit is that it handles not only Python, but also several other programming languages like C, C++, Java, etc.

No longer under development

Documentation processing tools

Other projects that can be used to produce API documentation

  • XIST - an XML based extensible HTML generator written in Python.

  • HtmlGen - a Python library for generating HTML documents.

Other documentation processing tools

  • Pandoc -- written in Haskell, this tool can read and write a number of formats (including reST).

  • Rippledoc (formerly known as Gouda) -- a command-line tool written in Clojure (using Pandoc under the hood) to generate multi-chapter html documents from Markdown text files.


CategoryDocumentation

DocumentationTools (last edited 2023-02-04 13:42:35 by GilOliveira)

Unable to edit the page? See the FrontPage for instructions.