[DOCS] Add admonition directive docs

Author: jaapio

docs/reference/restructuredtext/admonitions.rst

@@ -4,90 +4,16 @@
 Admonitions
 ===========
 
-The following directives are called "admonitions".
-You can use them to point out additional or important information.
+Admonitions are blocks of text that are rendered in a special way to draw attention to them. They are often used to
+provide additional information to the reader about the content that is being discussed.
 
 Examples
 ========
 
+.. index:: reST directives; seealso
+
 .. phpdoc:class-list:: [?(@.inheritedElement == "\phpDocumentor\Guides\RestructuredText\Directives\AbstractAdmonitionDirective")]
 
    .. phpdoc:name::
    .. phpdoc:summary::
-
-
-
-
-..  index:: reST directives; seealso
-
-See also
---------
-
-..  code-block:: rest
-
-    ..  seealso::
-        `Admonitions <http://docutils.sourceforge.net/0.7/docs/ref/rst/directives.html#admonitions>`__
-
-..  seealso::
-    `Admonitions <http://docutils.sourceforge.net/0.7/docs/ref/rst/directives.html#admonitions>`__
-
-
-..  index:: reST directives; note
-
-Note
-----
-
-..  code-block:: rest
-
-    ..  note::
-        A note
-
-..  note::
-    A note
-
-
-..  index:: reST directives; tip
-
-Tip
----
-
-..  code-block:: rest
-
-    ..  tip::
-        A tip
-
-..  tip::
-    A tip
-
-You may also use the admonition **hint**, but this is very similar
-and **tip** is more commonly used in the documentation.
-
-..  index:: reST directives; warning
-
-Warning
--------
-
-..  code-block:: rest
-
-    ..  warning::
-        Some text pointing out something that people should be warned about.
-
-..  warning::
-    Some text pointing out something that people should be warned about.
-
-You may also use the admonitions **caution** or even **danger** if the
-severity of the warning must be stressed.
-
-
-..  index:: reST directives; attention
-
-Attention
----------
-
-..  code-block:: rest
-
-    ..  attention::
-        A attention
-
-..  attention::
-    A attention
+   .. phpdoc:description::