Custom directives

RestructuredText supports directives, blocks of the form .. name:: data that can be used to extend the markup language with new behavior. phpDocumentor ships with directives for things like .. toctree:: and .. code-block:: , and you can add your own through an extension.

In our example we will create a .. hello:: directive that takes a name and greets it, e.g.:

.. hello:: World

A directive is a plain PHP class that extends . It needs a name, and it turns the parsed directive into a node:

<?php

declare(strict_types=1);

namespace phpDocumentor\Example\Directives;

use phpDocumentor\Example\Nodes\HelloNode;
use phpDocumentor\Guides\Nodes\Node;
use phpDocumentor\Guides\RestructuredText\Directives\BaseDirective;
use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
use phpDocumentor\Guides\RestructuredText\Parser\Directive;

final class HelloDirective extends BaseDirective
{
    public function getName(): string
    {
        return 'hello';
    }

    public function processNode(BlockContext $blockContext, Directive $directive): Node
    {
        return new HelloNode($directive->getData());
    }
}

• getName() returns the name that is used in the RST syntax, in our case hello .
• processNode() is called by the parser with the parsed (containing the data and options that were written after the directive) and returns the node that represents it in the document tree.

<?php

declare(strict_types=1);

use phpDocumentor\Example\Directives\HelloDirective;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $container): void {
    $container->services()
        ->defaults()
        ->autowire()
        ->autoconfigure()
        ->set(HelloDirective::class)
        ->tag('phpdoc.guides.directive')
    ;
};