Project

General

Profile

Actions

Story #20853

closed

Switch from pdoc3 to pdoc

Added by Brett Smith 7 months ago. Updated 6 months ago.

Status:
Resolved
Priority:
Normal
Assigned To:
Category:
Documentation
Target version:
Start date:
08/15/2023
Due date:
% Done:

100%

Estimated time:
(Total: 0.00 h)
Story points:
0.5
Release relationship:
Auto

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 --html command line switch from doc/Rakefile.
  • doc/sdk/python/python.html.textile.liquid needs to update its iframe src to be arvados.html (the file, not the subdirectory).
  • Update the pip install command in build/run-tests.sh and doc/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.


Subtasks 1 (0 open1 closed)

Task #20856: Review 20853-pdocResolvedPeter Amstutz08/15/2023

Actions

Related issues

Precedes Arvados - Story #20885: Revise Python docstring style for Markdown extensionsResolvedBrett Smith08/16/2023

Actions
Actions #1

Updated by Brett Smith 7 months ago

  • Description updated (diff)
Actions #2

Updated by Brett Smith 7 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
Actions #3

Updated by Brett Smith 7 months ago

  • Description updated (diff)
Actions #4

Updated by Brett Smith 7 months ago

  • Description updated (diff)
Actions #5

Updated by Brett Smith 7 months ago

  • Description updated (diff)
Actions #6

Updated by Brett Smith 7 months ago

  • Description updated (diff)
Actions #7

Updated by Peter Amstutz 7 months ago

  • Target version changed from To be groomed to Development 2023-08-30
Actions #8

Updated by Brett Smith 7 months ago

  • Assigned To set to Brett Smith
  • Status changed from New to In Progress
Actions #9

Updated by Brett Smith 7 months ago

20853-pdoc @ c2df493fdda20d9fd4e1cb92fc94e2b991ad4efe - developer-run-tests: #3777

Nobody review this just yet, I need to write up some caveats about minor regressions.

Actions #10

Updated by Brett Smith 6 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.

Actions #11

Updated by Peter Amstutz 6 months ago

This LGTM

Actions #12

Updated by Brett Smith 6 months ago

  • Status changed from In Progress to Resolved
Actions #13

Updated by Brett Smith 6 months ago

  • Precedes Story #20885: Revise Python docstring style for Markdown extensions added
Actions #14

Updated by Peter Amstutz 6 months ago

  • Release set to 66
Actions

Also available in: Atom PDF