[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::

packages/guides-restructured-text/src/RestructuredText/Directives/AttentionDirective.php

@@ -15,6 +15,17 @@
 
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 
+/**
+ * Directive to create an attention admonition.
+ *
+ * Example:
+ *
+ * ```rest
+ *  .. attention::
+ *
+ *      This is an attention admonition.
+ * ```
+ */
 final class AttentionDirective extends AbstractAdmonitionDirective
 {
     public function __construct(protected Rule $startingRule)

packages/guides-restructured-text/src/RestructuredText/Directives/CautionDirective.php

@@ -15,6 +15,17 @@
 
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 
+/**
+ * Directive to create a caution admonition.
+ *
+ * Example:
+ *
+ * ```rest
+ *  .. caution::
+ *
+ *      This is a caution admonition.
+ * ```
+ */
 final class CautionDirective extends AbstractAdmonitionDirective
 {
     public function __construct(protected Rule $startingRule)

packages/guides-restructured-text/src/RestructuredText/Directives/DangerDirective.php

@@ -15,7 +15,18 @@
 
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 
-final class DangerDirective extends AbstractAdmonitionDirective
+/**
+ * Directive to create a danger admonition.
+ *
+ * Example:
+ *
+ * ```rest
+ *  .. danger::
+ *
+ *      This is a danger admonition.
+ * ```
+ */
+class DangerDirective extends AbstractAdmonitionDirective
 {
     public function __construct(protected Rule $startingRule)
     {

packages/guides-restructured-text/src/RestructuredText/Directives/ErrorDirective.php

@@ -15,6 +15,17 @@
 
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 
+/**
+ * Directive to create a error admonition.
+ *
+ * Example:
+ *
+ * ```rest
+ *  .. error::
+ *
+ *      This is an error admonition.
+ * ```
+ */
 final class ErrorDirective extends AbstractAdmonitionDirective
 {
     public function __construct(protected Rule $startingRule)

packages/guides-restructured-text/src/RestructuredText/Directives/HintDirective.php

@@ -15,6 +15,17 @@
 
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 
+/**
+ * Directive to create a hint admonition.
+ *
+ * Example:
+ *
+ * ```rest
+ *  .. hint::
+ *
+ *      This is a hint admonition.
+ * ```
+ */
 final class HintDirective extends AbstractAdmonitionDirective
 {
     public function __construct(protected Rule $startingRule)

packages/guides-restructured-text/src/RestructuredText/Directives/ImportantDirective.php

@@ -15,6 +15,17 @@
 
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 
+/**
+ * Directive to create a important admonition.
+ *
+ * Example:
+ *
+ * ```rest
+ *  .. important::
+ *
+ *      This is a important admonition.
+ * ```
+ */
 final class ImportantDirective extends AbstractAdmonitionDirective
 {
     public function __construct(protected Rule $startingRule)

packages/guides-restructured-text/src/RestructuredText/Directives/NoteDirective.php

@@ -15,6 +15,17 @@
 
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 
+/**
+ * Directive to create a note admonition.
+ *
+ * Example:
+ *
+ * ```rest
+ *  .. note::
+ *
+ *      This is a note admonition.
+ * ```
+ */
 final class NoteDirective extends AbstractAdmonitionDirective
 {
     public function __construct(protected Rule $startingRule)

packages/guides-restructured-text/src/RestructuredText/Directives/SeeAlsoDirective.php

@@ -15,6 +15,17 @@
 
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 
+/**
+ * Directive to create a seealso admonition.
+ *
+ * Example:
+ *
+ * ```rest
+ *  .. seealso::
+ *
+ *      This is a seealso admonition.
+ * ```
+ */
 final class SeeAlsoDirective extends AbstractAdmonitionDirective
 {
     public function __construct(protected Rule $startingRule)

packages/guides-restructured-text/src/RestructuredText/Directives/TipDirective.php

@@ -15,6 +15,17 @@
 
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 
+/**
+ * Directive to create a tip admonition.
+ *
+ * Example:
+ *
+ * ```rest
+ *  .. tip::
+ *
+ *      This is a tip admonition.
+ * ```
+ */
 final class TipDirective extends AbstractAdmonitionDirective
 {
     public function __construct(protected Rule $startingRule)