define mark up for generic sphinx admonitions with a specific title

Question

I am using Sphinx to generate HTML documentation for a Python program.

I would like to use the generic admonition directive with a specific title and have it marked up in a way I can define, for example like content generated with the note directive, i.e., boxed, but with a different color (most Admonitions are not specially styled).

How do I best go about this?

How about using the [topic directive](http://docutils.sourceforge.net/docs/ref/rst/directives.html#topic)? — crayzeewulf, Jun 14 '16 at 00:17
@crayzeewulf: no, I semantically want it to be `admonition`; Bud's answer is perfectly fine. — equaeghe, Jun 15 '16 at 20:21

score 22 · Accepted Answer · answered Mar 16 '12 at 14:20

If I understood your question correctly, you'd like to apply a custon CSS style to the admonition. You can do this with a :class: attibute.

For example, the following

.. admonition:: my title goes here
   :class: myOwnStyle

   this is the admonition text

renders as

<div class="myownstyle admonition">
  <p class="first admonition-title">my title goes here</p>
  <p class="last">this is the admonition text</p>
</div>

You then add your own style sheet. For example, by a custom layout.html in the _templates directory in your source directory:

{% extends "!layout.html" %}
{% set css_files = css_files + ["_static/customstyle.css"] %}

Then you can play around with CSS styles in your style sheet using a selector for the myownstyle class

Took me hours to figure this out because I was not phrasing the question correctly to Google. Your answer is thorough and includes more useful information than I thought I could get. — Mad Physicist, Nov 20 '15 at 17:02
Good answer. Only thing missing for me is what the css file should look like. — Tim Skov Jacobsen, Mar 15 '20 at 13:44

score 6 · Answer 2 · answered Jun 15 '16 at 21:48

6

To add css files more easily, put them in the _static folder and then add this to conf.py:

def setup(app):
    app.add_stylesheet('custom.css')

answered Jun 15 '16 at 21:48

Gringo Suave

29,931
6
88
75

score 3 · Answer 3 · answered Apr 24 '20 at 23:21

Here is an example custom.css for overwriting the color of the title and background color of the myownstyle admonition. I used the app.add_stylesheet() call in conf.py.

.rst-content .myownstyle .admonition-title {
   background: #b99976
}

.rst-content .myownstyle {
   background: #e5d3b3
}

define mark up for generic sphinx admonitions with a specific title

3 Answers3

Linked