CODEWITHSUNDEEP
csspython-sphinxdirectiverestructuredtext
equaeghe
equaeghe

Reputation: 1784

define mark up for generic sphinx admonitions with a specific title

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?

Upvotes: 22

Views: 5669

Answers (4)

wsrt
wsrt

Reputation: 211

Here are my take on this:

  1. Requirements to be fulfilled for adding static files:

    • In conf.py:

      Add the following:

      • html_static_path = ['_static']

      • Adding path to css files:

        • Name of the css file to be be added to list html_css_files:

           html_css_files = [
    'css/some_file.css',
    'css/custom.css',  # Create a Custom CSS file and add
 ]

      • Note: As a corollary, the location of the CSS file would be (path): _static/css/custom.css (or any other folder name of choice in place of css)

  2. Add a class to admonition (or a directive) - details here

    As detailed above by @Bud here (being added for brevity):

       .. admonition:: A Title
      :class: clsMyTitle

  3. Create file custom.css (if not done already) and add the following:

     .admonition.clsmytitle {    /*Lowercase class name*/
     background-color: #e8cfe7;
     /* options as needed */
  }

  4. A parting note: As of today (2024), we may do all the above without having to take recourse to creating our own (custom) layout.html

  5. Tested in Sphinx v 7.2.6, Python 3.9

  6. To @Mad Physicist, one can always take a shot at: how to add class name to an admonition to .... (Actually I was looking for some direction at creating floating box in my page/s, and by accident (or by mercy of Google's famous algo) happened to land here.

Upvotes: 1

Rose Wahlin
Rose Wahlin

Reputation: 81

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
}

Upvotes: 4

Gringo Suave
Gringo Suave

Reputation: 31880

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')

Upvotes: 6

Bud P. Bruegger
Bud P. Bruegger

Reputation: 1091

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

Upvotes: 23

Related Questions