add best practice / fix class directive

Author: nikophil

_build/notes.md

@@ -21,3 +21,5 @@ Notes
 - add `&nbsp` instead of simple space to lines in code blocks
 - test if there is only one <h1> in each page
 - we're assuming there is only one toctree per page...
+- `rst` does not exist in highlight php
+- `varnish` = C ? (highlight php)

_build/src/Directive/BestPracticeDirective.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace SymfonyDocs\Directive;
+
+use Doctrine\RST\Nodes\Node;
+use Doctrine\RST\Nodes\WrapperNode;
+use Doctrine\RST\Parser;
+use Doctrine\RST\SubDirective;
+
+class BestPracticeDirective extends SubDirective
+{
+    public function getName(): string
+    {
+        return 'best-practice';
+    }
+
+    /**
+     * @param string[] $options
+     */
+    public function processSub(
+        Parser $parser,
+        ?Node $document,
+        string $variable,
+        string $data,
+        array $options
+    ): ?Node {
+        return new WrapperNode(
+            $document,
+            '<div class="admonition-best-practice admonition-wrapper"><div class="best-practice"></div><div class="admonition admonition-best-practice"><p class="admonition-title">Best Practice</p>',
+            '</div></div>'
+        );
+    }
+}

_build/src/Directive/ClassDirective.php

@@ -3,13 +3,12 @@
 namespace SymfonyDocs\Directive;
 
 use Doctrine\RST\Nodes\Node;
-use Doctrine\RST\Nodes\RawNode;
 use Doctrine\RST\Parser;
 use Doctrine\RST\SubDirective;
 
 class ClassDirective extends SubDirective
 {
-    public function getName() : string
+    public function getName(): string
     {
         return 'class';
     }
@@ -23,17 +22,9 @@ public function processSub(
         string $variable,
         string $data,
         array $options
-    ) : ?Node {
-        $dOMDocument = new \DOMDocument();
-        $dOMDocument->loadHTML((string) $document, LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);
+    ): ?Node {
+        $document->setClass($data);
 
-        /** @var \DOMElement $firstNode */
-        $firstNode = $dOMDocument->childNodes[0];
-        $firstNodeClass = $firstNode->getAttribute('class');
-        $firstNode->setAttribute('class', trim(sprintf('%s %s', $firstNodeClass, $data)));
-
-        return new RawNode($dOMDocument->saveHTML());
+        return $document;
     }
-
-
 }

_build/src/HtmlKernel.php

@@ -5,6 +5,7 @@
 use Doctrine\RST\Directive;
 use Doctrine\RST\Factory;
 use Doctrine\RST\HTML\Kernel;
+use SymfonyDocs\Directive\BestPracticeDirective;
 use SymfonyDocs\Directive\CautionDirective;
 use SymfonyDocs\Directive\ClassDirective;
 use SymfonyDocs\Directive\CodeBlockDirective;
@@ -89,6 +90,7 @@ public function getDirectives(): array
                 new SidebarDirective(),
                 new TipDirective(),
                 new VersionAddedDirective(),
+                new BestPracticeDirective(),
             ]
         );
     }

_build/src/Nodes/CodeNode.php

@@ -20,6 +20,12 @@ class CodeNode extends Base
         'php-annotations' => 'php',
         'text'            => 'text',
         'terminal'        => 'bash',
+        'markdown'        => 'markdown',
+        'rst'             => 'markdown',
+        'php-standalone'  => 'php',
+        'php-symfony'  => 'php',
+        'varnish4'  => 'c',
+        'varnish3'  => 'c',
     ];
 
     private const CODE_BLOCK_TEMPLATE = '<div class="literal-block notranslate">

_build/src/Nodes/ListNode.php

@@ -6,6 +6,9 @@
 
 class ListNode extends Base
 {
+    /** @var string */
+    private $class = '';
+
     protected function createElement(string $text, string $prefix): string
     {
         return sprintf('<li>%s</li>', $text);
@@ -19,8 +22,28 @@ protected function createList(bool $ordered): array
         $keyword = $ordered ? 'ol' : 'ul';
 
         return [
-            sprintf('<%s class="simple">', $keyword),
+            sprintf('<%s class="%s">', $keyword, trim('simple '.$this->class)),
             sprintf('</%s>', $keyword),
         ];
     }
+
+    /**
+     * @return string
+     */
+    public function getClass(): ?string
+    {
+        return $this->class;
+    }
+
+    /**
+     * @param string $class
+     *
+     * @return $this
+     */
+    public function setClass(?string $class)
+    {
+        $this->class = $class;
+
+        return $this;
+    }
 }

_build/tests/IntegrationTest.php

@@ -127,6 +127,10 @@ public function parserUnitBlockProvider()
             'blockName' => 'tip',
         ];
 
+        yield 'best-practice' => [
+            'blockName' => 'best-practice',
+        ];
+
         yield 'versionadded' => [
             'blockName' => 'versionadded',
         ];

_build/tests/fixtures/expected/blocks/best-practice.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8" />
+</head>
+<body>
+<div class="admonition-best-practice admonition-wrapper">
+    <div class="best-practice"></div>
+    <div class="admonition admonition-best-practice">
+        <p class="admonition-title">Best Practice</p>
+        <p>Use the bcrypt encoder for hashing your users' passwords.</p>
+    </div>
+</div>
+</body>
+</html>

_build/tests/fixtures/expected/main/datetime.html

@@ -88,6 +88,7 @@ <h3 id="date-widget">date_widget<a class="headerlink" href="#date-widget" title=
         </p>
     </div>
 </div>
+<p>This is included documentation about the <code class="notranslate">date_widget</code> option.</p>
 
 <h3 id="placeholder">placeholder<a class="headerlink" href="#placeholder" title="Permalink to this headline">¶</a></h3>
 <div class="versionadded">
@@ -131,6 +132,9 @@ <h3 id="placeholder">placeholder<a class="headerlink" href="#placeholder" title=
     <li><code class="notranslate">position</code></li>
     <li><code class="notranslate">toolbar</code></li>
     <li><code class="notranslate">verbose</code></li>
+    <li>
+        <a href="form/form_type.html#internal-reference" class="reference internal"><span>FormType Documentation</span></a>
+    </li>
 </ul>
 
 <h3 id="format">format<a class="headerlink" href="#format" title="Permalink to this headline">¶</a></h3>
@@ -156,6 +160,14 @@ <h3 id="format">format<a class="headerlink" href="#format" title="Permalink to t
     </div>
 </div>
 
+<div class="admonition-best-practice admonition-wrapper">
+    <div class="best-practice"></div>
+    <div class="admonition admonition-best-practice">
+        <p class="admonition-title">Best Practice</p>
+        <p>Use the bcrypt encoder for hashing your users' passwords.</p>
+    </div>
+</div>
+
 <h3 id="time-widget">time_widget<a class="headerlink" href="#time-widget" title="Permalink to this headline">¶</a></h3>
 
 <p><strong>type</strong>: <code class="notranslate">string</code> <strong>default</strong>: <code class="notranslate">choice</code></p>

_build/tests/fixtures/source/blocks/best-practice.rst

@@ -0,0 +1,4 @@
+
+.. best-practice::
+
+    Use the bcrypt encoder for hashing your users' passwords.

_build/tests/fixtures/source/main/datetime.rst

@@ -58,6 +58,8 @@ Date widget!
     the flow.
     :ref:`internal-reference`
 
+.. include:: /_includes/date_widget.rst.inc
+
 placeholder
 ~~~~~~~~~~~
 
@@ -92,6 +94,7 @@ Custom classes for links are also cool:
 * ``position``
 * ``toolbar``
 * ``verbose``
+* :ref:`internal-reference`
 
 format
 ~~~~~~
@@ -110,6 +113,10 @@ as a datetime string. See `Date/Time Format Syntax`_.
 
     Using too many sidebars or caution directives can be distracting!
 
+.. best-practice::
+
+    Use the bcrypt encoder for hashing your users' passwords.
+
 time_widget
 ~~~~~~~~~~~