Idea #20853
closed
Switch from pdoc3 to pdoc
Description
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 fromdoc/Rakefile.
doc/sdk/python/python.html.textile.liquidneeds to update itsiframe srcto bearvados.html(the file, not the subdirectory).
- Update the
pip installcommand inbuild/run-tests.shanddoc/README.textile.
There are output differences that we'll need to go over but it's at least as complete as the output we currently get.
Related issues
Updated by Brett Smith 9 months ago
- Description updated (diff)
- Subject changed from Updates required to generate PySDK documentation with pdoc>=12.2.0 to Switch from pdoc3 to pdoc
Updated by Peter Amstutz 9 months ago
- Target version changed from Future to Development 2023-08-30
Updated by Brett Smith 9 months ago
- Assigned To set to Brett Smith
- Status changed from New to In Progress
Updated by Brett Smith 9 months ago
20853-pdoc @ c2df493fdda20d9fd4e1cb92fc94e2b991ad4efe - developer-run-tests: #3777
Nobody review this just yet, I need to write up some caveats about minor regressions.
Updated by Brett Smith 9 months ago
20853-pdoc @ 6214997f9c61b40e25a31b9ca7d6b63b9a158837 - developer-run-tests: #3778
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.api, arvados.api_resources, and 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.
Updated by Brett Smith 9 months ago
- Status changed from In Progress to Resolved
Applied in changeset arvados|b20fb44b419ba6dd800874552bcfb5b87479611d.
Updated by Brett Smith 9 months ago
- Precedes Idea #20885: Revise Python docstring style for Markdown extensions added