[DOCS] Document writing an extension

and extending the templates

Author: linawolf

docs/extension/_YourExtension.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace T3Docs\Typo3DocsTheme\DependencyInjection;
+
+use Symfony\Component\Config\FileLocator;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Extension\Extension;
+use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
+
+use Symfony\Component\DependencyInjection\Loader\PhpFileLoader;
+use function dirname;
+
+class Typo3DocsThemeExtension extends Extension implements PrependExtensionInterface
+{
+    /** @param mixed[] $configs */
+    public function load(array $configs, ContainerBuilder $container): void
+    {
+    }
+
+    public function prepend(ContainerBuilder $container): void
+    {
+        $loader = new PhpFileLoader(
+            $container,
+            new FileLocator(dirname(__DIR__, 2) . '/resources/config'),
+        );
+        $loader->load('your-extension.php');
+        $container->prependExtensionConfig('guides', [
+            'themes' => [
+                'typo3docs' => [
+                    'extends' => 'bootstrap',
+                    'templates' => [dirname(__DIR__, 2) . '/resources/template'],
+                ],
+            ],
+        ]);
+    }
+}

docs/extension/_composer.json

@@ -0,0 +1,15 @@
+{
+  "name": "t3docs/typo3-docs-theme",
+  "description": "A theme for use in the phpdocumentor",
+  "type": "library",
+  "license": "MIT",
+  "homepage": "https://docs.typo3.org",
+  "autoload": {
+    "psr-4": {
+      "T3Docs\\Typo3DocsTheme\\": "src/"
+    }
+  },
+  "require": {
+    "phpdocumentor/guides-theme-bootstrap": "dev-main"
+  }
+}

docs/extension/_your-extension.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+use YourVendor\YourExtension\Directives\SomeDirective;
+
+return static function (ContainerConfigurator $container): void {
+    $container->services()
+        ->defaults()
+        ->autowire()
+        ->autoconfigure()
+        ->set(SomeDirective::class)
+        ->tag('phpdoc.guides.directive');
+};

docs/extension/index.rst

@@ -14,7 +14,8 @@ which you invoke the CLI.
 
 It should look like this::
 
-.. code-block:: xml
+..  code-block:: xml
+    :caption: your_project/guides.xml
 
     <?xml version="1.0" encoding="UTF-8" ?>
     <guides>
@@ -30,4 +31,6 @@ Some ways to extend the guides:
 
 .. toctree::
 
+    structure
+    templates
     text-roles

docs/extension/structure.rst

@@ -0,0 +1,62 @@
+..  include:: /include.rst.txt
+
+..  _extension_structure:
+
+=================
+General Structure
+=================
+
+You can extend the guides with your own Composer-based Symfony extension.
+
+..  _extension_composer:
+
+composer.json
+=============
+
+Each Composer package must have a file `composer.json`. See an example here:
+
+..  literalinclude:: _composer.json
+    :language: json
+    :caption: your-extension/composer.json
+    :lineos:
+
+The PHP sources can be found in the directory `src` then as is stated in line 8
+in the `composer.json`. 
+
+..  _extension_symfony:
+
+Create an extension
+===================
+
+For the PHP package to be an extension you need a class
+extending `\Symfony\Component\DependencyInjection\Extension\Extension` by 
+implementing the interface 
+`Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface` we
+can also add our ow configurations to our extension:
+
+..  literalinclude:: _YourExtension.php
+    :language: php
+    :caption: your-extension/DependencyInjection/YourExtension.php
+    :lineos:
+
+Lines 24 to 28 load a :ref:`Dependency Injection configuration <extension_di_configuration>` 
+file. Lines 29 to 36 configure the directory overriding the default templates. 
+Read chapter :ref:`extending_templates` to learn more about this.
+
+..  note::
+    This is a Symfony extension, not a TYPO3 extension. See also the
+    `Symfony documentation about Extensions <https://symfony.com/doc/current/bundles/extension.html>`__.
+
+..  _extension_di_configuration:
+
+Dependency Injection configuration
+===================================
+
+..  literalinclude:: _your-extension.php
+    :language: php
+    :caption: your-extension/resources/config/your-extension.php
+    :lineos:
+
+This is the place to register custom classes such as directives, text roles,
+custom compiler passes etc. You can also read about configuration files here:
+https://symfony.com/doc/current/bundles/configuration.html

docs/extension/templates.rst

@@ -0,0 +1,53 @@
+..  include:: /include.rst.txt
+
+..  _extending_templates:
+
+===================
+Extending Templates
+===================
+
+Register the templates overrides in your extensions 
+:ref:`Extension class <extension_symfony>`:
+
+..  literalinclude:: _YourExtension.php
+    :language: php
+    :caption: your-extension/DependencyInjection/YourExtension.php
+    :lineos:
+    :emphasize-lines: 29-35
+
+It is recommended to always extend an existing template so that the base 
+templates twig files can be used as fallback for non-defined specific template 
+files.
+
+In order to extend the default bootstrap theme, require the according base 
+extension in your extension's `composer.json`:
+
+..  code-block:: json
+    :caption: your-extension/composer.json
+
+    {
+      "name": "t3docs/typo3-docs-theme",
+      "...": "...",
+      "require": {
+        "phpdocumentor/guides-theme-bootstrap": "dev-main"
+      }
+    }
+
+And then set `'extends' => 'bootstrap'` (line 32 in the first code-snippet).
+
+To extend the base template (plain HTML) require `phpdocumentor/guides` in your 
+`composer.json`, and omit the key `extends`:
+
+
+..  code-block:: php
+    :caption: your-extension/DependencyInjection/YourExtension.php
+
+    $container->prependExtensionConfig('guides', [
+        'themes' => ['mytheme' => dirname(__DIR__, 3) . '/resources/template'],
+    ]);
+
+You can now copy any twig file from the extended extensions and change it with 
+the full power of `Twig <https://twig.symfony.com/>`__.
+
+Have a look at the `custom theme for TYPO3 Documentation <https://github.com/TYPO3-Documentation/typo3-docs-theme>`__
+for an example on how to create a theme which also features custom directives.