Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add backgrounds and borders to admonitions #190

Merged
merged 5 commits into from
Jun 24, 2024

Conversation

hugovk
Copy link
Member

@hugovk hugovk commented Jun 9, 2024

Only some of the "admonitions" have backgrounds and borders, giving them slightly different indentations:

image

We're missing backgrounds and borders for most of them:

Other themes have them for all:

Let's also fill in the gaps.

Before

image image

After

image image

Screenshots using this from the Kitchen Sink:

Details
..
   Copyright (c) 2021 Pradyun Gedam
   Licensed under Creative Commons Attribution-ShareAlike 4.0 International License
   SPDX-License-Identifier: CC-BY-SA-4.0

===========
Admonitions
===========

Sphinx provides several different types of admonitions.

``topic``
=========

.. topic:: This is a topic.

   This is what admonitions are a special case of, according to the docutils
   documentation.

   We also support *italic*, **bold**, ``code``, `links <https://www.sphinx-doc.org/>`_, and more.

``admonition``
==============

.. admonition:: The one with the custom titles

   It's got a certain charm to it.

   We also support *italic*, **bold**, ``code``, `links <https://www.sphinx-doc.org/>`_, and more.

``attention``
=============

.. attention::

   Climate change is real.

   We also support *italic*, **bold**, ``code``, `links <https://www.sphinx-doc.org/>`_, and more.

``caution``
===========

.. caution::

   Cliff ahead: Don't drive off it.

   We also support *italic*, **bold**, ``code``, `links <https://www.sphinx-doc.org/>`_, and more.

``danger``
==========

.. danger::

   Mad scientist at work!

   We also support *italic*, **bold**, ``code``, `links <https://www.sphinx-doc.org/>`_, and more.

``error``
=========

.. error::

   Does not compute.

   We also support *italic*, **bold**, ``code``, `links <https://www.sphinx-doc.org/>`_, and more.

``hint``
========

.. hint::

   Insulators insulate, until they are subject to ______ voltage.

   We also support *italic*, **bold**, ``code``, `links <https://www.sphinx-doc.org/>`_, and more.

``important``
=============

.. important::

   Tech is not neutral, nor is it apolitical.

   We also support *italic*, **bold**, ``code``, `links <https://www.sphinx-doc.org/>`_, and more.

``note``
========

.. note::

   This is a note.

   We also support *italic*, **bold**, ``code``, `links <https://www.sphinx-doc.org/>`_, and more.

``seealso``
===========

.. seealso::

   Other relevant information.

   We also support *italic*, **bold**, ``code``, `links <https://www.sphinx-doc.org/>`_, and more.

``tip``
=======

.. tip::

   25% if the service is good.

   We also support *italic*, **bold**, ``code``, `links <https://www.sphinx-doc.org/>`_, and more.

``warning``
===========

.. warning::

   Reader discretion is strongly advised.

   We also support *italic*, **bold**, ``code``, `links <https://www.sphinx-doc.org/>`_, and more.

Copy link
Member

@ezio-melotti ezio-melotti left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I left a few nitpicky comments, and I also have some additional bikeshedding, since the color choice of some admonition seems somewhat arbitrary to me:

  • attention seems to belong to the category of "potentially dangerous things that you should pay attention too", alongside important, caution, danger, warning, and error. I would probably place it between important and caution, color them gray/yellow, and then proceed with orange/red for more dangerous things -- using blue for attention feels wrong to me.
  • Similarly hint, note, see also, tip are all more neutral admonitions, and for those those I would use a neutral color like gray, blue, or possibly yellow -- green stands out a bit too much IMHO.

We should also check how they look on some real-world example, and see if the colors (and maybe the boxes too) are too distracting. This might actually be the reason why they weren't added in the first place (maybe we should check with the original author too and ask them why they made that choice).

We might also want to leave the bikeshedding for a separate PR (especially if you just copied the colors from another theme) as not to stall this PR.

python_docs_theme/static/pydoctheme.css Show resolved Hide resolved
python_docs_theme/static/pydoctheme.css Show resolved Hide resolved
python_docs_theme/static/pydoctheme_dark.css Outdated Show resolved Hide resolved
@hugovk
Copy link
Member Author

hugovk commented Jun 24, 2024

Thanks all for the reviews, let's merge and release. We can adjust and iterate the others in the future.

@hugovk hugovk merged commit af191cc into python:main Jun 24, 2024
9 checks passed
@hugovk hugovk deleted the admonition-colour branch June 24, 2024 13:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants