pdoc: Auto-generated Python Documentation

Tags: python, documentation, tooling
Published: 2021-09-10 17:58:37

*This short post looks at `pdoc`, a lightweight documentation
generator for Python programs, provides an example used on the logline docs page, and explores some advantages of automatic docgen for the pragmatic programmer.*

## Radical simplicity

[pdoc](https://pdoc3.github.io/pdoc/doc/pdoc) is a super simple tool for auto-generating Python program documentation.

> Python package `pdoc` provides types, functions, and a command-line interface for accessing public documentation of Python modules, and for presenting it in a user-friendly, industry-standard open format. It is best suited for small- to medium-sized projects with tidy, hierarchical APIs.

It's a `pip` package, so a simple command-line installation will have you up and running in seconds. `pdoc` is a lightweight alternative to Sphinx with minimal cognitive overhead. If you love `Markdown` you'll probably love `pdoc`. And if you don't love it, you'll like it.

## Less is more

You can output your documentation in PDF or HTML format with a simple flag:
   
 ```bash
 pdoc --PDF <filename>
 pdoc --HTML <filename>
```

The PDF option is a personal favorite because it produces a nice `LaTeX` document that would make Donald Knuth smile. You can even push it to the [arXiv](https://arxiv.org/) and pretend you're a physicist.

Autogenerated documentation is not exactly the Platonic ideal of [literate programming](https://en.wikipedia.org/wiki/Literate_programming), but if you have well-docstringed modules, functions, and classes, pdoc produces a user-friendly breakdown of your code into clean, modular sub-headings.

## The AKQ Game

The Ace-King-Queen Game is a toy model poker game written in Python. You can check out the [GitHub repo here](https://github.com/leemthompo/A-K-Q). It's a command-line game that contains the essence of hand ranges, bluffing frequencies, and calling frequencies, in a cartoonishly simple three-card game for two players. This implementation pits the human player against an _artificially intelligent_ computer player.

I used `pdoc` to auto-generate the HTML [documentation for the game](https://www.logline.fr/docs/AKQ/). A few tweaks and it was fit to publish on the **logline** website.

## The Overview Effect

Per [Wikipedia](https://en.wikipedia.org/wiki/Overview_effect):

> The **overview effect** is a cognitive shift in awareness reported by some astronauts during spaceflight, often while viewing the Earth from outer space.

On a more mundane plane, checking out your code at a high level can be clarifying, where you inspect the atomic elements of a script neatly arranged and indexed. The beauty of `pdoc` is how lightweight and fast it makes the docgen process. You can use it as part of an iterative development workflow --- to take a periodic birds-eye view of your code and survey the big picture.

Function-wise inspection of a program makes a lot of sense. If all the function names and docstrings pass the smell test after a quick run through `pdoc`, you're probably on the right path. Otherwise, it can help weed out faulty logic or potential missteps before they sabotage your script.