Arvados

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.

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

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.)

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.

it's not an SDK, and it's not sample code in documentation, so it should be AGPL 3.0.

Sure, that makes sense.