Guides

Text Roles

If restructured-text parsing is used, custom text roles can be defined.

If the text role does not need special parsing you can use the generic template. In this case it is sufficient to introduce a new template in path resources/template/html/guides/inline/textroles/ . See also Example: Introduce a basic custom text role.

For more complex examples you can implement \phpDocumentor\Guides\RestructuredText\TextRoles\TextRole and let the method processNode return a custom \phpDocumentor\Guides\Nodes\InlineToken . If this token extends \phpDocumentor\Guides\Nodes\GenericTextRoleToken the template will be automatically resolved by the name of the type. For more control rendering you can also implement your own token renderer.

Complex text roles that need processing during compilation can be adjusted in the passes. Have a look at the \phpDocumentor\Guides\Compiler\Passes\ReferenceResolverPass for an example.

Example: Introduce a basic custom text role

Let us assume we want to introduce a text role yaml-code . Create a new template resources/template/html/guides/inline/textroles/yaml-code.twig.html :

<code class="yaml some-styling">{{ textrole.content }}</code>

Example: Introduce an extended custom text role

  1. Extend class \phpDocumentor\Guides\RestructuredText\TextRoles\GenericTextRoleToken . You can have a look at \phpDocumentor\Guides\RestructuredText\TextRoles\AbbreviationTextRole for an example.
  2. Register the new class with the tag phpdoc.guides.parser.rst.text_role in the dependency injection configuration.
  3. Create a template using your introduced additional values.

Search results