|
Size: 4232
Comment: add pydoctor
|
← Revision 47 as of 2023-02-04 13:42:35 ⇥
Size: 5261
Comment: Updated outdated Sphinx links
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| 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 [[API Extraction|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 [[http://daringfireball.net/projects/markdown/|Markdown]]. == Python docstrings == |
|
| Line 8: | Line 27: |
| The various documentation tools available generally do one of two things: * they either process docstrings in some way to make finding/reading documentation on a given module easier (so-called "API documentation tools"), or * they have nothing to do with docstrings and instead focus on processing documentation in some way (such as converting your plain text docs into html) Currently, the Python docs consist of 2 parts: * the API docs that you can read using the `help()` command (pydoc can also provide these as html and even serve them from your local machine), and * the manuals/guides/howtos at http://python.org/doc/ which are written in reStructuredText (a plain text format) and processed into various output formats by the Sphinx tool. When writing documentation for your own modules (either as manuals or docstrings (preferably both)), I suggest you use a plain text markup such as reST or [[http://daringfireball.net/projects/markdown/|Markdown]]. |
|
| Line 22: | Line 30: |
| * PyDoc, http://pydoc.org/ documentation browser (in HTML) and/or an off-line reference manual. Also in the standard library as [[http://docs.python.org/lib/module-pydoc.html|pydoc]] | * [[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. * [[https://pdoc.dev/|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 ... * [[https://pdoc3.github.io/pdoc/|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 ... * [[https://www.pydoc.io|PyDoc]], a documentation browser (in HTML) and/or an off-line reference manual. Also in the standard library as [[http://docs.python.org/lib/module-pydoc.html|pydoc]]. * [[https://launchpad.net/pydoctor|pydoctor]], a replacement for now inactive Epydoc, born for the needs of Twisted project. * [[http://www.doxygen.org|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 [[http://graphviz.org/|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 = * Another PythonDoc - uses JavaDoc-style comments, and produces HTML and XML output. Can also be used as a library, producing ElementTree descriptions of your source code. http://effbot.org/zone/pythondoc.htm |
| Line 24: | Line 42: |
| * pydoctor, http://codespeak.net/~mwh/pydoctor/ replacement for now inactive Epydoc, pydoctor was born far the needs of Twisted project | * [[https://svn.enthought.com/enthought/wiki/EndoHowTo|Endo]] from Enthought Tool Suite - generates HTML API documentation from docstrings and from plain comments that immediately precede variable assignments. * [[http://pudge.lesscode.org/|Pudge]] (defunct) * [[http://happydoc.sourceforge.net/|HappyDoc]] ([[http://sourceforge.net/projects/happydoc/forums/forum/30132/topic/3563472?message=8100340|not supported]]) - documentation extraction tool that uses the parse tree for a module to derive the information used in its output, rather that importing the module directly. * EasyDoc - uses an HTML-like markup language, similar to the language used by Wiki:JavaDoc; and produces HTML output (http://htmltmpl.sourceforge.net/easydoc.html) |
| Line 26: | Line 47: |
| * Another PythonDoc - uses JavaDoc-style comments, and produces HTML and XML output. Can also be used as a library, producing ElementTree descriptions of your source code. http://effbot.org/zone/pythondoc.htm * EasyDoc - uses an HTML-like markup language, similar to the language used by Wiki:JavaDoc; and produces HTML output (http://htmltmpl.sourceforge.net/easydoc.html) * Doxygen < http://www.doxygen.org > 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 < http://www.research.att.com/sw/tools/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. * [[https://svn.enthought.com/enthought/wiki/EndoHowTo|Endo]] from Enthought Tool Suite - generates HTML API documentation from docstrings and from plain comments that immediately precede variable assignments. |
|
| Line 31: | Line 48: |
* [[http://happydoc.sourceforge.net/|HappyDoc]] ([[http://sourceforge.net/projects/happydoc/forums/forum/30132/topic/3563472?message=8100340|not supported]]) - documentation extraction tool that uses the parse tree for a module to derive the information used in its output, rather that importing the module directly. * [[http://pudge.lesscode.org/|Pudge]] (defunct) |
|
| Line 38: | 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 |
| Line 48: | Line 62: |
| * [[http://www.unexpected-vortices.com/sw/rippledoc/|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. |
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
Another PythonDoc - uses JavaDoc-style comments, and produces HTML and XML output. Can also be used as a library, producing ElementTree descriptions of your source code. http://effbot.org/zone/pythondoc.htm
Endo from Enthought Tool Suite - generates HTML API documentation from docstrings and from plain comments that immediately precede variable assignments.
Pudge (defunct)
HappyDoc (not supported) - documentation extraction tool that uses the parse tree for a module to derive the information used in its output, rather that importing the module directly.
EasyDoc - uses an HTML-like markup language, similar to the language used by JavaDoc; and produces HTML output (http://htmltmpl.sourceforge.net/easydoc.html)
PythonDoc - uses StructuredText input format (not reST), and can produce HTML and XML output. It uses XML as an intermediate representation, to simplify the addition of new output formats. http://starship.python.net/crew/danilo/pythondoc/
Apydia, http://apydia.ematia.de/
Documentation processing tools
DocUtils, http://docutils.sourceforge.net/ reStructuredText processing engine
Sphinx, https://www.sphinx-doc.org/ - converts reStructuredText documentation into various formats
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.