API doc generator.
Project description
This is pydoctor, an API documentation generator that works by static analysis.
It was written primarily to replace epydoc for the purposes of the Twisted project as epydoc has difficulties with zope.interface. If you are looking for a successor to epydoc after moving to Python 3, pydoctor might be the right tool for your project as well.
pydoctor puts a fair bit of effort into resolving imports and computing inheritance hierarchies and, as it aims at documenting Twisted, knows about zope.interface’s declaration API and can present information about which classes implement which interface, and vice versa.
Simple Usage
You can run pydoctor on your project like this:
$ pydoctor --make-html --html-output=docs/api src/mylib
For more info, Read The Docs.
Markup
pydoctor currently supports the following markup languages in docstrings:
- epytext (default)
The markup language of epydoc. Simple and compact.
- restructuredtext
The markup language used by Sphinx. More expressive than epytext, but also slighly more complex and verbose.
- plaintext
Text without any markup.
You can select a different format using the --docformat option.
What’s New?
pydoctor 20.12.1
Reject source directories outside the project base directory (if given), instead of crashing
Fixed bug where source directories containing symbolic links could appear to be outside of the project base directory, leading to a crash
Bring back source link on package pages
pydoctor 20.12.0
Python 3.6 or higher is required
There is now a user manual that can be built with Sphinx or read online on Read the Docs; this is a work in progress and the online version will be updated between releases
Added support for Python language features:
Type annotations of function parameters and return value are used when the docstring does not document a type
Functions decorated with @property or any other decorator with a name ending in “property” are now formatted similar to variables
Coroutine functions (async def) are included in the output
Keyword-only and position-only parameters are included in the output
Output improvements:
Type names in annotations are hyperlinked to the corresponding documentation
Styling changes to make the generated documentation easier to read and navigate
Private API is now hidden by default on the Module Index, Class Hierarchy and Index of Names pages
The pydoctor version is included in the “generated by” line in the footer
All parents of the HTML output directory are now created by pydoctor; previously it would create only the deepest directory
The --add-package and --add-module options have been deprecated; pass the source paths as positional arguments instead
New option -W/--warnings-as-errors to fail your build on documentation errors
Linking to the standard library documentation is more accurate now, but does require the use of an intersphinx inventory (--intersphinx=https://docs.python.org/3/objects.inv)
Caching of intersphinx inventories is now enabled by default
Added a Sphinx extension for embedding pydoctor’s output in a project’s Sphinx documentation
Added an extra named rst for the dependencies needed to process reStructuredText (pip install -U pydoctor[rst])
Improved error reporting:
More accurate source locations (file + line number) in error messages
Warnings were added for common mistakes when documenting parameters
Clearer error message when a link target is not found
Increased reliability:
Fixed crash when analyzing from package import *
Fixed crash when the line number for a docstring error is unknown
Better unit test coverage, more system tests, started adding type annotations to the code
Unit tests are also run on Windows
pydoctor 20.7.2
Fix handling of external links in reStructuredText under Python 3
Fix reporting of errors in reStructuredText under Python 3
Restore syntax highlighting of Python code blocks
pydoctor 20.7.1
Fix cross-reference links to builtin types in standard library
Fix and improve error message printed for unknown fields
pydoctor 20.7.0
Python 3 support
Type annotations on attributes are supported when running on Python 3
Type comments on attributes are supported when running on Python 3.8+
Type annotations on function definitions are not supported yet
Undocumented attributes are now included in the output
Attribute docstrings: a module, class or instance variable can be documented by a following it up with a docstring
Improved error reporting: more errors are reported, error messages include file name and line number
Dropped support for implicit relative imports
Explicit relative imports (using from) no longer cause warnings
Dropped support for index terms in epytext (X{}); this was never supported in any meaningful capacity, but now the tag is gone
This will be the last major release to support Python 2.7 and 3.5: future major releases will require Python 3.6 or later.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pydoctor-20.12.1-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 42ad373353e8e93744dbd402258ed0cbd208cf2bb444d5b734e64ee38fc26516 |
|
| MD5 | d7976a503668842d11279de0804b3329 |
|
| BLAKE2b-256 | f38f108873a109c1681121a063dfb41fa75378acd8a6fc9314a5867a8d4c1a0d |
