Opened 3 years ago

Closed 3 years ago

Last modified 2 years ago

#19317 closed Cleanup/optimization (fixed)

Make warning blocks distinguishable

Reported by: tome Owned by: nobody
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: no UI/UX: no

Description

This is suggestion to make the warning block in the docs distinguishable from the note blocks, as they contain a different type of information.

Most (but not all) instances of the warning block are written like this:

.. warning::

This way the blocks get the class "warning", which might not be a specific enough target for css styling. The "philosophy" and "behind the scenes" blocks on the other hand use the following syntax:

.. admonition:: Philosophy

In the example, the div gets a class of "admonition-philosophy". This is then referred to in the spinx theme css and gives the block a philosophy icon.

The suggestion is to use the same notation for warning boxes:

.. admonition:: Warning

This is already used in a few places in the docs. With this, the divs get the "admonition-warning" class, to which we can safely apply a different styling - my suggestion is an orange border and an orange icon.

A suggested icon and a patch for the sphinx theme css are attached, as well as a screenshot of the result.

Attachments (3)

warning_css_class.diff (820 bytes) - added by tome 3 years ago.
docicons-warning.png (782 bytes) - added by tome 3 years ago.
Warning block icon
warning_block_screenshot.png (66.3 KB) - added by tome 3 years ago.
Screenshot of proposed warning block

Download all attachments as: .zip

Change History (10)

Changed 3 years ago by tome

Changed 3 years ago by tome

Warning block icon

Changed 3 years ago by tome

Screenshot of proposed warning block

comment:1 Changed 3 years ago by tome

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Type changed from Uncategorized to Cleanup/optimization

comment:2 Changed 3 years ago by timo

+1 from me, we can use .admonition.warning for the CSS selector to achieve the desired effect rather than changing the existing markup.

comment:3 Changed 3 years ago by jezdez

  • Patch needs improvement set
  • Triage Stage changed from Unreviewed to Accepted

comment:4 Changed 3 years ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from new to closed

In 3587991ba8d223fe9fe4d54a094b82dbc9c27bc2:

Fixed #19317 - Added an image for warning blocks in the docs

Thanks tome for the suggestion and patch.

comment:5 Changed 3 years ago by Tim Graham <timograham@…>

In 74e22f97725d4c85564c9d5210d8cdc19b19520d:

[1.5.X] Fixed #19317 - Added an image for warning blocks in the docs

Thanks tome for the suggestion and patch.

Backport of 3587991ba8 from master

comment:6 Changed 3 years ago by Tim Graham <timograham@…>

In 9ee9a7265a76d435d886942ee431a216564d13f0:

[1.4.X] Fixed #19317 - Added an image for warning blocks in the docs

Thanks tome for the suggestion and patch.

Backport of 3587991ba8 from master

comment:7 Changed 2 years ago by Tim Graham <timograham@…>

In b7f991fe8dac92c9cf2f36f04c745e9b9973ef45/djangoproject.com:

Fixed #19317 - Added an image for warning blocks in the docs

Thanks tome for the suggestion and patch.

Note: See TracTickets for help on using tickets.
Back to Top