Pydoctor

pydoctor

.. image:: https://img.shields.io/pypi/pyversions/pydoctor.svg :target: https://pypi.python.org/pypi/pydoctor

.. image:: https://github.com/twisted/pydoctor/actions/workflows/unit.yaml/badge.svg :target: https://github.com/twisted/pydoctor/actions/workflows/unit.yaml

.. 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, a standalone 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 --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 slightly more complex and verbose.

`google`__
    Docstrings formatted as specified by the Google Python Style Guide. 
    (compatible with reStructuredText markup)

`numpy`__
    Docstrings formatted as specified by the Numpy Docstring Standard. 
    (compatible with reStructuredText markup)

``plaintext``
    Text without any markup.

__ http://epydoc.sourceforge.net/manual-epytext.html
__ https://docutils.sourceforge.io/rst.html
__ https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings
__ https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

You can select a different format using the ``--docformat`` option or the ``__docformat__`` module variable. 

What's New?
~~~~~~~~~~~

in development
^^^^^^^^^^^^^^

* Hide sidebar element title when all items under it are private.
* Allow suppressing the footer's buildtime altogether with option ``--buildtime=no``.
* Add project version on each HTML page.
* When an  intersphinx inventory file fails to read, exit with code 2 and do not print the whole stack trace by default. 
  The -v flag will log exceptions' tracebacks.

pydoctor 25.10.1
^^^^^^^^^^^^^^^^

* Fix the tag name of the release. 

pydoctor 25.10.0
^^^^^^^^^^^^^^^^

* Add support for doc-comments as found in Sphinx. Use the special comment formatting ``#:`` to start the comment instead of just ``#``.
  Comments need to be either on a line of their own before the definition, or immediately after the assignment on the same line. 
* Fix a bug with inline docstrings, if there is comment in between an assignment and literal string, 
  the string will not be misinterpreted as being a docstring.
* Fix a regression that prevented the source link on package' page to be rendered.
* Improve introspection of C-modules to support data descriptors.
* Dunders that are not supposed to be part of the API are now ignored when introspecting code.
* Fix bug, ``ivar`` field and fiends are not ignored anymore in introspected C-modules.
* Fix bug that would result in duplicated "Cannot find link target" warnings when the 
  types under a docstring *Attributes* section failed to resolved.
* Introduce --intersphinx-file option: Use local Sphinx objects inventory file to generate 
  links to external documentation. If the optional base URL is provided, the links will be 
  made relative to this base URL. Can be repeated. Format is *PATH_TO_OBJECTS.INV[::BASE_URL]*. 
* Allow to pass a custom base URL when loading inventory files from URL. The format is
  *URL_TO_OBJECTS.INV[::BASE_URL]*.
* Fixes a bug where the `__docformat__` variable of a parent package would be ignored if an import 
  shortcuts the default processing order, leading to process the docstrings with system's docformat 
  instead of the one specified in the parent package `__docformat__`.
* Prefer newer "tomli" package over "toml".
* Fix a bug that made impossible to highlight some attributes or functions because 
  their name clashed with other HTML IDs. Custom templates using HTML ID `main` should
  now use `<main>` tag instead. Custom templates using HTML ID `showPrivate`, `summaryTree`, 
  `childList`, `splitTables` and `collapseSideBar` should use hyphen-separated ID instead (like `show-private`).


pydoctor 25.4.0
^^^^^^^^^^^^^^^

* Drop support for Python 3.8.
* Add support for `Namespace Packages <https://packaging.python.org/en/latest/guides/packaging-namespace-packages>`_: 
  
  - Support implicit native namespace packages (PEP 420). Get rid of the error: ``Source directory lacks __init__.py``. 
  - Some limited support for legacy namespace packages is included as well (with ``declare_namespace(__name__)`` or ``__path__ = extend_path(__path__, __name__)``).
  - Better messages are now triggered when there is a module/package name collision (exit code will not change though).

* Signatures of function definitions are now wrapped onto several lines when the function has the focus. 
* The first parameter of classmethods and methods (``cls`` or ``self``) is colored in gray so it's clear that these are not part of the API.
* When pydoctor encounters an invalid signature, it shows (…) as the signature instead of the misleading zero argument signature.
* Improve field tables so the correspondence with the description column is more legible.
* Highlighting in readthedocs theme now cover the whole docstring content 
  instead of just the signature.
* Fix a bug in the MRO computing code that would result in an incorrect  
  ``Cannot compute linearization of the class inheritance hierarchy`` message 
  for valid types extending ``typing.Generic`` as well as other generic classes.

pydoctor 24.11.2
^^^^^^^^^^^^^^^^

* Replace deprecated usage of ``datetime.datetime.utcfromtimestamp()``

pydoctor 24.11.1
^^^^^^^^^^^^^^^^

* Fix a bug that would cause a variable marked as `Final` not being considered as a constant if
  it was declared under a control-flow block.
* Fix a bug in google and numpy "Attributes" section in module docstring: 
  the module attributes now shows as "Variables" instead of "Instance Variables".

pydoctor 24.11.0
^^^^^^^^^^^^^^^^

* Drop Python 3.7 and support Python 3.13.
* Implement canonical HTML element (``<link rel="canonical" href="..."/>``) to help search engines reduce outdated content. 
  Enable this feature by passing the base URL of the API documentation with option ``--html-base-url``.
* Improve collection of objects:
   - Document objects declared in the ``else`` block of 'if' statements (previously they were ignored).
   - Document objects declared in ``finalbody`` and ``else`` block of 'try' statements (previously they were ignored).
   - Objects declared in the ``else`` block of if statements and in the ``handlers`` of 'try' statements
     are ignored if a concurrent object is declared before (`more infos on branch priorities <https://pydoctor.readthedocs.io/en/latest/codedoc.html#branch-priorities>`_).
* Trigger a warning when several docstrings are detected for the same object.
* Improve typing of docutils related code.
* Run unit tests on all supported combinations of Python versions and platforms, including PyPy for Windows. Previously, tests where ran on all supported Python version for Linux, but not for MacOS and Windows.
* Replace the deprecated dependency appdirs with platformdirs.
* Fix WinError caused by the failure of the symlink creation process.
  Pydoctor should now run on windows without the need to be administrator.
* Adjust the sphinx extension to support Sphinx 8.1. The entries dynamically added to the intersphinx config
  from the ``pydoctor_url_path`` config option now includes a project name which defaults to 'main' (instead of putting None), 
  use mapping instead of a list to define your own project name.
* Improve the themes so the adds injected by ReadTheDocs are rendered with the correct width and do not overlap too much with the main content.
* Fix an issue in the readthedocs theme that prevented to use the search bar from the summary pages (like the class hierarchy).
* The generated documentation now includes a help page under the path ``/apidocs-help.html``. 
  This page is accessible by clicking on the information icon in the navbar (``ℹ``).
* Improve the javascript searching code to better understand terms that contains a dot (``.``).


pydoctor 24.3.3
^^^^^^^^^^^^^^^

* Fix release pipeline.

pydoctor 24.3.0
^^^^^^^^^^^^^^^

This is the last major release to support Python 3.7.

* Drop support for Python 3.6.
* Add support for Python 3.12.
* Astor is no longer a requirement starting at Python 3.9.
* `ExtRegistrar.register_post_processor()` now supports a `priority` argument that is an int.
  Highest priority callables will be called first during post-processing.
* Fix too noisy ``--verbose`` mode (suppres some ambiguous annotations warnings).
* Fix type processing inside restructuredtext consolidated fields.
* Add options ``--cls-member-order`` and ``--mod-member-order`` to customize the presentation
  order of class members and module/package members, the supported values are "alphabetical" or "source".
  The default behavior is to sort all members alphabetically.
* Make sure the line number coming from ast analysis has precedence over the line of a ``ivar`` field.
* Ensure that all docutils generated css classes have the ``rst-`` pre