Custom Directives

Directive Class

You can write your own directives by defining a class that extends the Doctrine\RST\Directives\Directive class and defines the method getName() that returns the directive name.

You can then implement one of the following methods:

• processAction() if your directive simply tweak the document without modifying the nodes
• processNode() if your directive is adding a node
• process() if your directive is tweaking the node that just follows it

See Directive.php for more information.

Example Directive

1
namespace App\RST\Directives;

use Doctrine\RST\Nodes\Node;
use Doctrine\RST\Parser;
use Doctrine\RST\Directives\Directive;

class ExampleDirective extends Directive
{
    public function getName() : string
    {
        return 'example';
    }

    /**
     * @param string[] $options
     */
    public function process(
        Parser $parser,
        ?Node $node,
        string $variable,
        string $data,
        array $options
    ) : void {
        // do something to $node
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

Now you can register your directive by passing it to the 2nd argument of the Doctrine\RST\Kernel class:

1
use App\RST\Directives\ExampleDirective;

$kernel = new Kernel($configuration, [
    new ExampleDirective()
]);

$builder = new Builder($kernel);
2
3
4
5
6
7

SubDirective Class

You can also extend the Doctrine\RST\Directives\SubDirective class and implement the processSub() method if you want the sub block to be parsed. Here is an example CautionDirective:

1
namespace App\RST\Directives;

use Doctrine\RST\Nodes\Node;
use Doctrine\RST\Nodes\WrapperNode;
use Doctrine\RST\Parser;
use Doctrine\RST\Directives\SubDirective;

class CautionDirective extends SubDirective
{
    public function getName() : string
    {
        return 'caution';
    }

    /**
     * @param string[] $options
     */
    public function processSub(
        Parser $parser,
        ?Node $document,
        string $variable,
        string $data,
        array $options
    ) : ?Node {
        $divOpen = $parser->renderTemplate('div-open.html.twig', [
            'class' => 'caution',
        ]);

        return $parser->getNodeFactory()->createWrapperNode($document, $divOpen, '</div>');
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

Now you can use the directive like this and it can contain other reStructuredText syntaxes:

.. caution::

    This is some **bold** text!

The above example would output the following HTML:

1
<div class="caution"><p>This is some <strong>bold</strong> text!</p></div>