Switch from pdoc3 to pdoc
pdoc3 is a semi-hostile fork of pdoc, it seems to be less maintained (last release in 2021 vs. June this year for pdoc), and the maintainer thinks it's cute to put a swastika on their web site to make people “question their assumptions.” They still use a very swastika-like image as their GitHub profile picture too.
Switching to original pdoc is fairly easy:
- Remove the
--htmlcommand line switch from
doc/sdk/python/python.html.textile.liquidneeds to update its
iframe srcto be
arvados.html(the file, not the subdirectory).
- Update the
pip installcommand in
There are output differences that we'll need to go over but it's at least as complete as the output we currently get.
Updated by Brett Smith 6 months ago
pdoc doesn't handle some of the Markdown extensions that pdoc3 does and that we built our docstring style around. Specifically, definition lists (used for argument lists) and callouts (used for deprecation notices). We'll need to revisit those and figure out new ways to render them nicely, either by updating our style, or maybe there's a way we can extend pdoc.
But right now in main, the only stuff documented in that style is
arvados.retry (which is barely user-facing). Given that our style is already inconsistent and rough in spots, my personal preference would be to merge this now, and make a follow-up ticket to revisit the fancier styling.
One benefit we get from this switch is that pdoc does a better job of rendering the TypedDicts in
arvados.api_resources. It's still not perfect but a lot clearer what's going on. It only shows keys that have pseudo-docstrings, so after we do #19929 I think that page will look really slick.