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:

• Markdown
• numpydoc
• Google-style docstrings

At this time, pdoc3 doesn’t consider Python type hinting.

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 html/pymap3d/index.html

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

mv html/pymap3d/*.html docs/

Publish the docs to the web by:

1. In the Github repo Settings → Github Pages → Source: “gh-pages”
2. git commit and push. It takes a few seconds for Github Pages to deploy HTML.