pydoctor
--------

.. image:: https://travis-ci.org/twisted/pydoctor.svg?branch=tox-travis-2
  :target: https://travis-ci.org/twisted/pydoctor

.. image:: https://codecov.io/gh/twisted/pydoctor/branch/master/graph/badge.svg
  :target: https://codecov.io/gh/twisted/pydoctor

.. image:: https://img.shields.io/badge/-documentation-blue
  :target: https://pydoctor.readthedocs.io/

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.

.. contents:: Contents:


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 <https://pydoctor.readthedocs.io/>`_.

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.

__ http://epydoc.sourceforge.net/manual-epytext.html
__ https://docutils.sourceforge.io/rst.html

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

__ https://pydoctor.readthedocs.io/
__ https://pydoctor.readthedocs.io/en/latest/usage.html#building-pydoctor-together-with-sphinx-html-build

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.

.. description-end
