[DOCS] Document the renderer

Author: linawolf

docs/components/_renderer/_PlaintextRenderer.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MyExtension\Renderer;
+
+use phpDocumentor\Guides\Renderer\BaseTypeRenderer;
+
+final class PlaintextRenderer extends BaseTypeRenderer
+{
+}

docs/components/_renderer/_myextension.php

@@ -0,0 +1,18 @@
+<?php
+
+use MyVendor\MyExtension\Renderer\PlaintextRenderer;
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+
+return static function (ContainerConfigurator $container): void {
+    $container->services()
+        ->defaults()->autowire()
+        // ...
+        ->set(PlaintextRenderer::class)
+        ->tag(
+            'phpdoc.renderer.typerenderer',
+            [
+                'noderender_tag' => 'phpdoc.guides.noderenderer.txt',
+                'format' => 'txt',
+            ],
+        );
+};

docs/components/renderer.rst

@@ -6,5 +6,58 @@
 Renderer
 ========
 
-..  warning::
-    This needs to be documented
+A Renderer transforms the :abbreviation:`AST (abstract syntax tree)` into a
+desired output format.
+
+The most common renderers handle each document separately. For example the
+:php:class:`\phpDocumentor\Guides\Renderer\HtmlRenderer` renders the AST into
+HTML.
+
+Each renderer must implement
+:php:interface:`\phpDocumentor\Guides\Renderer\TypeRenderer`.
+
+Basic document
+type renderers like the HTML or Latex renderer can extend
+the :php:class:`\phpDocumentor\Guides\Renderer\BaseTypeRenderer`. The
+:php:`BaseTypeRenderer` creates a
+:php:class:`\phpDocumentor\Guides\Handlers\RenderDocumentCommand` for each
+document in the document tree. The :php:`RenderDocumentCommand` passes the
+rendering to the NodeRenders which do the actual rendering.
+
+All renderers must be registered in the ContainerConfigurator of the extension
+with the tag :php:`'phpdoc.renderer.typerenderer'` and additional format information.
+
+Example: a plaintext renderer
+=============================
+
+Create a class called :php:`PlaintextRenderer` which just extends
+:php:class:`\phpDocumentor\Guides\Renderer\BaseTypeRenderer`.
+
+..  literalinclude:: _renderer/_PlaintextRenderer.php
+    :language: php
+    :caption: src/Renderer/PlaintextRenderer.php
+
+Register the new renderer in the container:
+
+..  literalinclude:: _renderer/_myextension.php
+    :language: php
+    :caption: resources/config/myextension.php
+
+You can now configure your project to also generate output in plaintext:
+
+..  code-block:: php
+    :caption: guides.xml
+
+    <?xml version="1.0" encoding="UTF-8" ?>
+    <guides xmlns="https://www.phpdoc.org/guides"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://www.phpdoc.org/guides packages/guides-cli/resources/schema/guides.xsd"
+    >
+        <extension class="MyVendor\MyExtension"/>
+        <output-format>txt</output-format>
+    </guides>
+
+You can now define :ref:`custom templates <extending_templates>` or even custom
+NodeRenderer for the new output format.
+
+..  todo: document NodeRenderer and then link them from here.

docs/index.rst

@@ -46,5 +46,6 @@ If you are looking for a complete solution to create a documentation website the
     cli/index
     developers/index
     architecture
+    components/index
     reference/index
     contributions/index