Differentiate styling of epigraph, pull-quote and highlight elements

[tuukkamustonen]

Epigraph, highlights and pull-quote look 100% alike now:

.. epigraph::

   No matter where you go, there you are.

   -- Buckaroo Banzai

.. highlights::

   This is a highlight.

.. pull-quote::

   Pull quote example.

Wouldn't it make sense to differentiate them a bit?

Using italic for highlights should be at least removed and perhaps that block should be, indeed, highlighted a bit?

---

All these generate blockquote HTML element but differing class names:

<blockquote class="epigraph">...
<blockquote class="highlights">...
<blockquote class="pull-quote">...

...which is maybe a bit weird, because "highlights" definitively doesn't sound like quotation (so why does docutils render it as blockquote? Don't know).

Currently, the styling is done on blockquote element directly, so the same gets applied to all three.

[pradyunsg]

Got examples of how some other Sphinx themes present these?

[tuukkamustonen]

sphinx-book-theme seems to have some opinion on pull-quote vs epigraph. Nutshell: Epigraph is larger, a pull-quote smaller.

insipid-sphinx-theme seems to have similar convention. It also implements highlights (without text being italic unlike with pull-quote/epigraph). Scroll to bottom of the page to see them.

sphinx-rtd-theme only defines block quote but none of the 3 directives.

It's a bit hard to find examples of these... They are probably not that often used elements, perhaps something one discovers only after years of writing docs (happened to me!).

(All these should be added to Furo's Kitchen Sink, too.)

[pradyunsg]

This was done at some point: https://pradyunsg.me/furo/kitchen-sink/blocks/

[tuukkamustonen]

Excellent. Thanks!