Idea #20885
closedRevise Python docstring style for Markdown extensions
Description
This ticket has some history:
In #18797 we developed a docstring style that looks good in plaintext and in our rendered web documentation. It uses a couple less-standard Markdown extensions: definition lists for argument lists, and !!!
callouts for deprecation notices.
In #20853 we switched from pdoc3 to pdoc to generate our web documentation. It doesn't support these Markdown extensions, at least not out of the box.
- Research options. If we can configure pdoc (maybe with extensions?) to support this markup, that's one possibility. Otherwise, develop another style that still looks good.
- Update the style guide in our wiki
- Update existing documentation written in the #18797 style. As of this writing that's docstrings in
arvados.retry
,arvados.api
, andarvados.api_resources
(generated bydiscovery2pydoc.py
).
Related issues
Updated by Brett Smith about 1 year ago
- Follows Idea #18797: Flesh out python sdk documentation in docstrings & ensure good presentation in pydoc added
- Start date set to 11/14/2022
- Due date set to 11/14/2022
Updated by Brett Smith about 1 year ago
- Follows Idea #20853: Switch from pdoc3 to pdoc added
- Start date changed from 11/14/2022 to 08/16/2023
- Due date changed from 11/14/2022 to 08/16/2023
Updated by Peter Amstutz about 1 year ago
- Target version changed from To be scheduled to Development 2023-09-13 sprint
Updated by Peter Amstutz about 1 year ago
- Target version changed from Development 2023-09-13 sprint to Development 2023-09-27 sprint
Updated by Brett Smith about 1 year ago
Notes so far:
You basically can't customize pdoc beyond the command line options offered. No configuration file or anything like that. Anything advanced requires writing your own script that uses the API. Fortunately it is laid out nicely so you can make a couple tweaks then just call the command line's main entry point.
pdoc uses the markdown2 library, and you have access to its extras. Extras are configured in pdoc.render_helpers.markdown_extensions
.
There is an adminitions extension that could provide our deprecation warnings. The syntax is a little different but I think it's basically a wash in terms of plaintext readability. I'd be fine using it.
There's nothing for definition lists, and that bums me out, because the more I go over other options the more I definitely feel like it's the right thing for argument lists. I'll sleep on it though.
You can use a different Markdown renderer completely, basically by setting render.env.filters['to_html']
to a rendering function that takes a Markdown string argument and returns an HTML string. However this is not officially supported and may cause other weirdnesses. I'm not sure I want to go there.
Meh. Nothing's perfect.
Updated by Brett Smith about 1 year ago
20885-pdoc-style @ 0d868ba0ba58f1bdf4e75d8651d894c39d1f69ff - developer-run-tests: #3836
This branch ends up doing everything contemplated. It adds a wrapper script to configure pdoc with additional Markdown extras we want.
The proposed style for arguments is list-style, because that's the only plaintext presentation I didn't completely hate. Note three dashes to get an em dash:
* name: type --- Description
The proposed style for deprecation notices is reST-style:
.. WARNING:: Deprecated Deprecation background and suggested alternative.
This branch updates all Python documentation that was updated for the previous style. If this branch is accepted, I will update the guidelines wiki to codify these new styles. I will also write a story to add CSS styles to our web documentation to improve the rendering of the admonitions (the HTML is good enough to do that).
- All agreed upon points are implemented / addressed.
- Done
- Anything not implemented (discovered or discussed during work) has a follow-up story.
- N/A
- Code is tested and passing, both automated and manual, what manual testing was done is described
- See above. Also reviewed generated web documentation manually.
- Documentation has been updated.
- Done
- Behaves appropriately at the intended scale (describe intended scale).
- N/A
- Considered backwards and forwards compatibility issues between client and server.
- N/A
- Follows our coding standards and GUI style guidelines.
- Done
Updated by Peter Amstutz about 1 year ago
- Target version changed from Development 2023-09-27 sprint to Development 2023-10-11 sprint
Updated by Tom Clegg about 1 year ago
Seems like pysdk_pdoc.py should have the CC-BY-SA-3.0 license like other things in doc/, rather than AGPL-3.0?
Other than that, LGTM.
(Definition lists do seem like they were actually made for this, so it's annoying not to be able to use them, but bulleted lists with em dashes look pretty good.)
Updated by Brett Smith about 1 year ago
Tom Clegg wrote in #note-9:
Seems like pysdk_pdoc.py should have the CC-BY-SA-3.0 license like other things in doc/, rather than AGPL-3.0?
I'm maybe anticipating #20827 a little bit here. While we haven't made a decision on what we want the license of documentation code to be, I think there's consensus it should not be CC BY-SA. CC themselves recommends against using their licenses for software.
Given that, AGPL 3.0 is the license that follows the rules in the current Arvados README: it's not an SDK, and it's not sample code in documentation, so it should be AGPL 3.0. If we decide to relax that rule later, that's no big deal, and it can be done as part of a general doc/
licensing cleanup.
Updated by Brett Smith about 1 year ago
- Precedes Feature #21018: Add CSS to pdoc to improve admonition rendering added
Updated by Tom Clegg about 1 year ago
it's not an SDK, and it's not sample code in documentation, so it should be AGPL 3.0.
Sure, that makes sense.
Updated by Brett Smith about 1 year ago
- Status changed from New to Resolved
Applied in changeset arvados|72f74086108b60a46458895411dd9afdaae8f383.