Project

General

Profile

Actions

Idea #20885

closed

Revise Python docstring style for Markdown extensions

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

Status:
Resolved
Priority:
Normal
Assigned To:
Category:
Documentation
Story points:
0.5
Release relationship:
Auto

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, and arvados.api_resources (generated by discovery2pydoc.py).

Subtasks 1 (0 open1 closed)

Task #20964: Review 20885-pdoc-styleResolvedBrett Smith08/16/2023Actions

Related issues

Follows Arvados - Idea #18797: Flesh out python sdk documentation in docstrings & ensure good presentation in pydocResolvedBrett Smith11/11/2022Actions
Follows Arvados - Idea #20853: Switch from pdoc3 to pdocResolvedBrett Smith08/15/2023Actions
Precedes Arvados - Feature #21018: Add CSS to pdoc to improve admonition renderingNewActions
Actions #1

Updated by Brett Smith 6 months 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
Actions #2

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

Updated by Peter Amstutz 6 months ago

  • Target version changed from To be scheduled to Development 2023-09-13 sprint
Actions #4

Updated by Peter Amstutz 6 months ago

  • Target version changed from Development 2023-09-13 sprint to Development 2023-09-27 sprint
Actions #5

Updated by Peter Amstutz 6 months ago

  • Assigned To set to Brett Smith
Actions #6

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

Actions #7

Updated by Brett Smith 5 months 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
Actions #8

Updated by Peter Amstutz 5 months ago

  • Target version changed from Development 2023-09-27 sprint to Development 2023-10-11 sprint
Actions #9

Updated by Tom Clegg 5 months 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.)

Actions #10

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

Actions #11

Updated by Brett Smith 5 months ago

  • Precedes Feature #21018: Add CSS to pdoc to improve admonition rendering added
Actions #12

Updated by Tom Clegg 5 months 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.

Actions #13

Updated by Brett Smith 5 months ago

  • Status changed from New to Resolved
Actions #14

Updated by Peter Amstutz 5 months ago

  • Release set to 67
Actions

Also available in: Atom PDF