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
Error
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.
Hint
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.
Warning
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.
Caution
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.
Hint
A .. hint:: is like a positive caution.
It always targets the (typical) reader of the document.
Important
Use .. important:: as a notice to a fellow/delegate writer
Note
Typical not in a final/delivered document.
This is used to describe what kind of information should be writen in that article/section.
Note
A .. note:: is just a generic note
Hardly used
Danger
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
comments powered by Disqus