Pdoc Python quickstart

Pdoc is vastly simpler to use than Sphinx for small projects, although the generated HTML is not as beautiful as Sphinx. Better to have uglier up-to-date docs than no docs or outdated docs.

In distinction from Sphinx, pdoc expects Markdown docstrings and does not parse RST docstrings.


pdoc is a light minimal install.

pip install pdoc


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

  1. From the top-level pymap3d/ directory, type
    pdoc --html pymap3d

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

  2. Check the output by:
    firefox pymap3d/index.html
  3. If the output seems satisfactory, move the files to the gh-pages branch, or at least to a docs/ folder:
    mv pymap3d/*.html docs/
  4. In the Github repo Settings → Github Pages → Source: “master branch /docs folder”
  5. git commit and push. It takes a few seconds for Github Pages to deploy HTML.


Written by Michael Hirsch, Ph.D. //