Differences between revisions 41 and 43 (spanning 2 versions)
Revision 41 as of 2019-05-03 17:03:05
Size: 5331
Editor: JaraKaca
Comment: Update pdoc3 description
Revision 43 as of 2019-05-06 21:11:36
Size: 5316
Editor: JaraKaca
Comment: Revise pdoc3 description. Thanks.
Deletions are marked like this. Additions are marked like this.
Line 33: Line 33:
 * [[https://pdoc3.github.io/pdoc/|pdoc3]], an updated and maintained fork of pdoc for Python 3. Includes support for Numpydoc/Google-style docstring formats, reST directives, PEP 484 type annotations, custom templates ...  * [[https://pdoc3.github.io/pdoc/|pdoc3]], an updated fork of pdoc for Python 3 which includes support for Numpydoc / Google-style docstrings, reST directives, PEP 484 type annotations, custom templates ...

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 command line tool and library to auto generate API documentation for Python modules. Designed to replace epydoc and works on both Python 2 and 3. Includes support for cross-linking across modules, documentation for variables and namedtuples, and a built-in HTTP server to view documentation of local packages.

  • pdoc3, an updated fork of pdoc for Python 3 which includes support for Numpydoc / Google-style docstrings, 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.