Project

General

Profile

Actions

Idea #20885

closed

Revise Python docstring style for Markdown extensions

Added by Brett Smith 11 months ago. Updated 9 months ago.

Status:
Resolved
Priority:
Normal
Assigned To:
Category:
Documentation
Start date:
08/16/2023
Due date:
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

Also available in: Atom PDF