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.

Install

pdoc is a light minimal install.

pip install pdoc

Usage

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, for cleanliness, move the files to the docs folder:
    mv pymap3d/*.html docs/
       
    git add 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.

Categories:

Comments

Written by Michael Hirsch, Ph.D. //