phpDocumentor Guides integration

.gitignore

@@ -1,8 +1,10 @@
-/vendor/
 /tests/_output
 /tests/_cache
 /var/
 /docs.phar
 /.env
+/.phpunit.cache/
 /.phpunit.result.cache
+/.php-cs-fixer.cache
 /composer.lock
+vendor/

.php-cs-fixer.dist.php

@@ -0,0 +1,34 @@
+<?php
+
+$fileHeaderComment = <<<EOT
+This file is part of the Guides SymfonyExtension package.
+
+(c) Wouter de Jong
+
+For the full copyright and license information, please view the LICENSE
+file that was distributed with this source code.
+EOT;
+
+return (new PhpCsFixer\Config())
+    ->setRules([
+        '@PHP71Migration' => true,
+        '@PHPUnit75Migration:risky' => true,
+        '@Symfony' => true,
+        '@Symfony:risky' => true,
+        'protected_to_private' => false,
+        'native_constant_invocation' => ['strict' => false],
+        'no_superfluous_phpdoc_tags' => [
+            'remove_inheritdoc' => true,
+            'allow_unused_params' => true, // for future-ready params, to be replaced with https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/issues/7377
+        ],
+        'header_comment' => ['header' => $fileHeaderComment],
+        'modernize_strpos' => true,
+        'get_class_to_class_keyword' => true,
+        'nullable_type_declaration' => true,
+    ])
+    ->setRiskyAllowed(true)
+    ->setFinder(
+        (new PhpCsFixer\Finder())
+            ->in(__DIR__.'/src')
+    )
+;

composer.json

@@ -14,24 +14,42 @@
         }
     },
     "require": {
-        "php": ">=8.3",
+        "php": ">=8.2",
         "ext-json": "*",
         "ext-curl": "*",
-        "doctrine/rst-parser": "^0.5",
-        "scrivo/highlight.php": "^9.18.1",
-        "symfony/filesystem": "^5.2 || ^6.0 || ^7.0",
-        "symfony/finder": "^5.2 || ^6.0 || ^7.0",
-        "symfony/dom-crawler": "^5.2 || ^6.0 || ^7.0",
-        "symfony/css-selector": "^5.2 || ^6.0 || ^7.0",
-        "symfony/console": "^5.2 || ^6.0 || ^7.0",
-        "symfony/http-client": "^5.2 || ^6.0 || ^7.0",
-        "twig/twig": "^2.14 || ^3.3"
+        "phpdocumentor/guides": "^1.9",
+        "phpdocumentor/guides-cli": "^1.9",
+        "phpdocumentor/guides-code": "^1.7",
+        "phpdocumentor/guides-restructured-text": "^1.9",
+        "scrivo/highlight.php": "^9.12.0",
+        "symfony/config": "^6.0",
+        "symfony/filesystem": "^6.0",
+        "symfony/finder": "^6.0",
+        "symfony/event-dispatcher": "^6.0",
+        "symfony/dependency-injection": "^6.0",
+        "symfony/dom-crawler": "^6.0",
+        "symfony/css-selector": "^6.0",
+        "symfony/console": "^6.0",
+        "symfony/http-client": "^6.0",
+        "symfony/string": "^6.0",
+        "twig/twig": "^3.3",
+        "twig/string-extra": "^3.6"
     },
     "require-dev": {
-        "gajus/dindent": "^2.0",
-        "symfony/phpunit-bridge": "^5.2 || ^6.0 || ^7.0",
-        "symfony/process": "^5.2 || ^6.0 || ^7.0",
-        "masterminds/html5": "^2.7"
+        "league/flysystem-memory": "^3.0",
+        "symfony/phpunit-bridge": "^7.4@dev",
+        "symfony/process": "^6.0",
+        "symfony/var-dumper": "^6.2"
     },
-    "bin": ["bin/docs-builder"]
+    "scripts": {
+        "test": "SYMFONY_PHPUNIT_VERSION=12 simple-phpunit",
+        "psalm": [
+            "composer update --no-scripts --working-dir=tools/psalm",
+            "./tools/psalm/vendor/bin/psalm"
+        ],
+        "cs": [
+            "composer update --no-scripts --working-dir=tools/php-cs-fixer",
+            "./tools/php-cs-fixer/vendor/bin/php-cs-fixer fix"
+        ]
+    }
 }

config/parser.php

@@ -0,0 +1,28 @@
+<?php
+
+/*
+ * This file is part of the Docs Builder package.
+ *
+ * (c) Ryan Weaver <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+use phpDocumentor\Guides\RestructuredText\Parser\Productions\DirectiveContentRule;
+use phpDocumentor\Guides\RestructuredText\TextRoles\TextRole;
+
+return static function (ContainerConfigurator $container) {
+    $container->services()
+        ->defaults()->autowire()
+
+        ->load('SymfonyDocsBuilder\\Directives\\', '../src/Directives')
+            ->bind('$startingRule', service(DirectiveContentRule::class))
+            ->tag('phpdoc.guides.directive')
+
+        ->load('SymfonyDocsBuilder\\TextRole\\', '../src/TextRole')
+            ->tag('phpdoc.guides.parser.rst.text_role')
+    ;
+};

config/renderer.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the Docs Builder package.
+ *
+ * (c) Ryan Weaver <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+use SymfonyDocsBuilder\Highlighter\SymfonyHighlighter;
+use SymfonyDocsBuilder\NodeRenderer\CodeNodeRenderer;
+use SymfonyDocsBuilder\NodeRenderer\MenuEntryRenderer;
+use SymfonyDocsBuilder\Node\ExternalLinkNode;
+use SymfonyDocsBuilder\Twig\CodeExtension;
+use SymfonyDocsBuilder\Twig\UrlExtension;
+use Twig\Extension\ExtensionInterface;
+use Twig\Extra\String\StringExtension;
+use phpDocumentor\Guides\Code\Highlighter\Highlighter;
+use phpDocumentor\Guides\NodeRenderers\NodeRenderer;
+use phpDocumentor\Guides\NodeRenderers\TemplateNodeRenderer;
+
+return static function (ContainerConfigurator $container) {
+    $container ->services()
+        ->defaults()->autowire()->autoconfigure()
+        ->instanceof(ExtensionInterface::class)->tag('twig.extension')
+        ->instanceof(NodeRenderer::class)->tag('phpdoc.guides.noderenderer.html', ['priority' => 10])
+
+        ->set(CodeExtension::class)
+        ->set(UrlExtension::class)
+        ->set(StringExtension::class)
+
+        ->set(CodeNodeRenderer::class)
+        ->set(MenuEntryRenderer::class)
+
+        ->set('symfony.node_renderer.html.inline.external_link', TemplateNodeRenderer::class)
+            ->arg('$template', 'inline/external-link.html.twig')
+            ->arg('$nodeClass', ExternalLinkNode::class)
+
+        ->set(SymfonyHighlighter::class)
+            ->decorate(Highlighter::class)
+    ;
+};

config/services.php

@@ -0,0 +1,30 @@
+<?php
+
+/*
+ * This file is part of the Docs Builder package.
+ *
+ * (c) Ryan Weaver <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+use Psr\EventDispatcher\EventDispatcherInterface;
+use SymfonyDocsBuilder\Build\BuildConfig;
+use SymfonyDocsBuilder\DocBuilder;
+use Symfony\Component\Console\Output\ConsoleOutput;
+use Symfony\Component\EventDispatcher\EventDispatcher;
+
+return static function (ContainerConfigurator $container) {
+    $container->services()
+        ->defaults()->autowire()
+
+        ->set(EventDispatcherInterface::class, EventDispatcher::class)
+
+        ->set(BuildConfig::class)
+
+        ->set(DocBuilder::class)->public()
+    ;
+};

phpunit.xml

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/12.4/phpunit.xsd"
+    bootstrap="vendor/autoload.php"
+    beStrictAboutOutputDuringTests="true"
+    failOnDeprecation="true"
+    failOnRisky="true"
+    failOnWarning="true"
+    cacheDirectory=".phpunit.cache"
+    beStrictAboutCoverageMetadata="true">
+    <testsuites>
+        <testsuite name="default">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <source ignoreSuppressionOfDeprecations="true"
+        ignoreIndirectDeprecations="true"
+        restrictNotices="true"
+        restrictWarnings="true">
+        <include>
+            <directory>src</directory>
+        </include>
+
+        <deprecationTrigger>
+            <function>trigger_deprecation</function>
+            <method>Doctrine\Deprecations\Deprecation::trigger</method>
+            <method>Doctrine\Deprecations\Deprecation::delegateTriggerToBackend</method>
+        </deprecationTrigger>
+    </source>
+</phpunit>

psalm.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0"?>
+<psalm
+    errorLevel="2"
+    resolveFromConfigFile="true"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xmlns="https://getpsalm.org/schema/config"
+    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
+    findUnusedCode="false"
+    findUnusedBaselineEntry="true"
+>
+    <projectFiles>
+        <directory name="src" />
+        <directory name="config" />
+        <ignoreFiles>
+            <directory name="vendor" />
+        </ignoreFiles>
+    </projectFiles>
+
+    <issueHandlers>
+        <ImplicitToStringCast errorLevel="suppress" />
+    </issueHandlers>
+</psalm>

resources/highlight.php/README.md

@@ -0,0 +1,30 @@
+# Custom Highlight Templates
+
+The highlight.php library takes its highlighting metadata/rules
+from highlight.js. That library builds the highlighting metadata/rules
+in Node and then outputs them as JSON:
+
+* Source Language files: https://github.com/highlightjs/highlight.js/tree/master/src/languages
+* Final Language files: https://github.com/scrivo/highlight.php/tree/master/Highlight/languages
+
+In a few cases, we've extended the language rules, which (in theory)
+should make it back upstream to highlight.js. These files began
+as copies of the .json files (which were then prettified) then extended.
+
+A few things we've learned about how the language files work:
+
+* `begin` is the regex that marks the beginning of something
+* `end` is optional. Without it, `begin` will be used, and as
+    soon as it finds a non-matching character, it will stop.
+    If you have a situation where using begin is causing
+    over-matching, then you can use end to tell it exactly where
+    to stop.
+* `excludeEnd` can be used to match an entire string with `begin`
+    and `end`, but then only apply the class name to the part
+    matched by `start`. This was useful with `::` where we wanted
+    to match `::` THEN some valid string (to avoid over-matching
+    `::` in other situations). But, we only wanted the class name
+    applied to the `start` part (the `::` part).
+* `contains` the way for building embedded rules. `function` is
+    a nice example, which outlines the `start` and `end` and then
+    also outlines some items that will be embedded inside of it.