Pdoc Python quickstart

Pdoc is vastly simpler to use than Sphinx for small projects, with good HTML formatting.

In distinction from Sphinx, pdoc does not parse RST docstrings, but Pdoc does allow the following docstring formats:

At this time, pdoc3 doesn’t consider Python type hinting; hopefully they’ll add that in the future.

Install

pdoc is a light minimal install.

pip install pdoc3

Usage

We use the pymap3d project with auto-generated docs as an example.

From the top-level pymap3d/ directory, type

pdoc --html pymap3d

This creates several *.html files under html/pymap3d, including index.html.

Check the output by:

firefox pymap3d/index.html

If the output seems satisfactory, move the files to the gh-pages branch, or at least to a docs/ folder:

mv pymap3d/*.html docs/

Publish the docs to the web by:

  1. In the Github repo Settings → Github Pages → Source: “master branch /docs folder”
  2. git commit and push. It takes a few seconds for Github Pages to deploy HTML.