Admonitions (overview & use)

Sphinx (and RST) support several “admons” or admonitions to make the reader aware of hazard or other parts of text that should stand out. But it hardly tells anything on which to use, in which case.

Therefore, I list them and give some advise when to use them

And, you can also see how the look like. Note however, the rendering depends on your configuration, especially the style (aka: which ccs) is used.

Frequently used


Use .. error:: when tools/process can go wrong, and can’t continue.

This directive notices the user (or manual-reader) when things really (can) go wrong. This implies and the tool/process can’t continue.


Although this admonition is in the frequently used list, a sound design & documentation should minimize the number of errors, and so this admonition shouldn’t be seen often.


The .. warning:: directive is to signal on “tricky” items. Probably it can be correct, but often it will wrong So, it’s not an error, and the tool/process can continue – possible with a wrong output.


Use .. caution:: to warn the reader about the document itself.

E.g. when the document does not have the same status/release as the product/tool and can be misleading.
Now the solution is typical to update the docs.


A .. hint:: is like a positive caution.

It always targets the (typical) reader of the document.


Use .. important:: as a notice to a fellow/delegate writer


Typical not in a final/delivered document.

This is used to describe what kind of information should be writen in that article/section.


A .. note:: is just a generic note

Hardly used


This is even more wrong than en error; possible life-threading.

Therefore the .. danger:: directive should hardly be used; not is software tools.

generic admonition

The generic ..admonition:: (with parameter!) can be used when no standard admonition is available. Use reluctantly


comments powered by Disqus