Project

General

Profile

Actions

Feature #21018

open

Add CSS to pdoc to improve admonition rendering

Added by Brett Smith about 1 year ago. Updated 7 months ago.

Status:
New
Priority:
Normal
Assigned To:
-
Category:
Documentation
Target version:
Story points:
0.5

Description

We use admonitions for deprecation notices in the Python SDK. The HTML comes out like this:

<aside class="admonition warning">
    <strong>WARNING</strong>
    <em>Deprecated</em>
    <p><a href="#clear_tmpdir">clear_tmpdir</a> is deprecated and scheduled to be removed in Arvados 3.0.</p>
</aside>

None of this has any styling, so it's pretty plain and a little difficult to follow. Add CSS to do the following:

  • Give the whole aside block a yellow background to distinguish it from other documentation.
  • Add content with punctuation to better separate the strong and the em.
  • Add aside.admonition em { font-weight: normal; }
  • Consider aside.admonition strong { text-transform: uppercase; }

See this pdoc FAQ and the few that follow for instructions on how to do this. Customizing the pdoc invocation can be done by extending doc/pysdk_pdoc.py.


Related issues

Follows Arvados - Idea #20885: Revise Python docstring style for Markdown extensionsResolvedBrett Smith08/16/2023Actions
Actions

Also available in: Atom PDF