pdoc

Auto-generate API documentation for Python projects

Ever finished a neat Python script only to see it later lay unused by anyone at all because the only documenting effort you gave it was the petty README.md? Ever found Sphinx too cumbersome to use for the small project on your hands or have repeatedly found reST syntax for links too volatile to touch-type, whereas you had always loved and adored Markdown? Many have. Documentation is a PITA to maintain. Real programmers don't document their programs — documentation is for simpletons who can't read object code from memory dumps. Right? Wrong.

Documentation is like sex: when it is good, it is very, very good;
and when it is bad, it is better than nothing.

— Dick B.

Enter pdoc, the perfect documentation generator for small-to-medium-sized, tidy Python projects. It generates documentation simply from your project's already-existing public modules' and objects' docstrings, like sphinx-apidoc or sphinx.ext.autodoc, but without the hassle of these tools. Minimal and lightweight. Guaranteed 99% correct magic out of the box!

  • Compatible with Python 3+

    Python 3.6 and up. Best choice for new or forward-looking projects.

  • Common docstring formats

    Out-of-the-box support for markdown, numpydoc, Google-style docstrings, Napoleon, doctests, and some common reST directives.

  • Zero configuration

    Pdoc works automatically, following common Python programming conventions. Simply run the command line script, ecstatically nodding in agreement.

  • Docs hierarchy follows module hierarchy

    Use module docstrings to introduce topics. Literate programming as Guido intended it.

  • Customizable templates

    Pdoc uses fast mako templating engine. The default templates should suit most cases, but they can easily be customized, extended or overridden.

  • Easy cross-linking of identifiers

    Simply wrap object references in backticks and let the technology do all the rest.

  • Integrated dev web server

    Instant feedback on your doc writing skills — see it as you write it.

  • Dependable

    Unmatched identifiers and source errors raise loud warnings. Reliably build documentation in your CI pipeline.

  • Plain text, HTML, or PDF output

    Functionally laid out for every kind of eye.

Download

* PyPI package pdoc3. Not to be confused with an older package pdoc this package is a fork of.

Usage

* Replace second pdoc with your package / directory / file name to view the documentation of your project.

What Users are Saying

The proof of [this] program's value is its existence.

Alan Perlis

All this technology is completely unnecessary to a happy life.

Tom Hodgkinson

[...] When all else fails, read the instructions.

Cahn

Based on Markdown, lighter than Sphinx — a really nice #python #documentation tool.

I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature.

Donald Knuth