How to change format of Warning admonition or add Caution in Sphinx HTML output

Question

This seems like it should be straightforward but I've been prowling the documentation and web and haven't found the answer.

I want to output HTML doc from Sphinx. Ideally I'd like to have three levels of "note" type highlighted text boxes. ReST defines several "admonitions": (http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions) but most of the Sphinx HTML themes include special formatting only for Note and Warning. (I am using one of the preinstalled themes, Classic.)

I have two questions:

1) How can I customize the color behind Warning in my documents?

2) How can I add a formatting style for Caution?

I see that these all end up with tags like <div class="admonition warning"> ... in the HTML output. But I can't find where the formatting for that class is defined. Is it in a stylesheet? Is it in a layout.html file or some other file?

Is there anything that explains how the various files in themes actually interact with each other? I haven't found a good primer. (I am no expert on css-based HTML either, so maybe that's part of the problem.)

Answer 1

Okay, I figured out more and have a working workaround. (I'm still not sure how I'm supposed to handle this.)

Looks like my HTML code is reading directly from a few cascading stylesheets stored along with the output in a directory called _static. There's classic.css, which inherits from basic.css.

I don't understand how these relate to the files named like basic.css_t that live in the Python Sphinx install.

To change things, should I (A) try altering the _t files? or (B) create an altered local copy of classic.css that lives in my source directory?

If I go with B, more questions.

• Will it be overwritten by the values in the css_t template at build time? (I guess this is easy enough to test)
• Is it good practice to use the same filename for a modified version of that stylesheet?

Here's a workaround that avoids those questions and seems to be doing what I want - from this: https://github.com/snide/sphinx_rtd_theme/issues/117

• I created an override stylesheet that includes just the formatting I want to change.
• I stored it in the _static of my source directory.

• I defined it in my conf.py as follows:

  html_context = {
      'css_files': [
          '_static/theme_overrides.css', 
          ],
      }
  

Now, that github discussion said that this wasn't a solution for all kinds of themes (including the RTD theme mentioned in the question) but I think I'm safe for now.

What more should I know?