Skip to content

Commit 4965a7d

Browse files
wouterjwouterj
committed
Merge phpDocumentor Guides extension in the DocsBuilder
2 parents 1fa3d6a + c954ea7 commit 4965a7d

File tree

160 files changed

+9837
-153
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

160 files changed

+9837
-153
lines changed

‎.gitignore‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1-
/vendor/
21
/tests/_output
32
/tests/_cache
43
/var/
54
/docs.phar
65
/.env
6+
/.phpunit.cache/
77
/.phpunit.result.cache
8+
/.php-cs-fixer.cache
89
/composer.lock
10+
vendor/

‎.php-cs-fixer.dist.php‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<?php
2+
3+
$fileHeaderComment = <<<EOT
4+
This file is part of the Guides SymfonyExtension package.
5+
6+
(c) Wouter de Jong
7+
8+
For the full copyright and license information, please view the LICENSE
9+
file that was distributed with this source code.
10+
EOT;
11+
12+
return (new PhpCsFixer\Config())
13+
->setRules([
14+
'@PHP71Migration' => true,
15+
'@PHPUnit75Migration:risky' => true,
16+
'@Symfony' => true,
17+
'@Symfony:risky' => true,
18+
'protected_to_private' => false,
19+
'native_constant_invocation' => ['strict' => false],
20+
'no_superfluous_phpdoc_tags' => [
21+
'remove_inheritdoc' => true,
22+
'allow_unused_params' => true, // for future-ready params, to be replaced with https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/issues/7377
23+
],
24+
'header_comment' => ['header' => $fileHeaderComment],
25+
'modernize_strpos' => true,
26+
'get_class_to_class_keyword' => true,
27+
'nullable_type_declaration' => true,
28+
])
29+
->setRiskyAllowed(true)
30+
->setFinder(
31+
(new PhpCsFixer\Finder())
32+
->in(__DIR__.'/src')
33+
)
34+
;

‎composer.json‎

Lines changed: 33 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -14,24 +14,42 @@
1414
}
1515
},
1616
"require": {
17-
"php": ">=8.3",
17+
"php": ">=8.2",
1818
"ext-json": "*",
1919
"ext-curl": "*",
20-
"doctrine/rst-parser": "^0.5",
21-
"scrivo/highlight.php": "^9.18.1",
22-
"symfony/filesystem": "^5.2 || ^6.0 || ^7.0",
23-
"symfony/finder": "^5.2 || ^6.0 || ^7.0",
24-
"symfony/dom-crawler": "^5.2 || ^6.0 || ^7.0",
25-
"symfony/css-selector": "^5.2 || ^6.0 || ^7.0",
26-
"symfony/console": "^5.2 || ^6.0 || ^7.0",
27-
"symfony/http-client": "^5.2 || ^6.0 || ^7.0",
28-
"twig/twig": "^2.14 || ^3.3"
20+
"phpdocumentor/guides": "^1.9",
21+
"phpdocumentor/guides-cli": "^1.9",
22+
"phpdocumentor/guides-code": "^1.7",
23+
"phpdocumentor/guides-restructured-text": "^1.9",
24+
"scrivo/highlight.php": "^9.12.0",
25+
"symfony/config": "^6.0",
26+
"symfony/filesystem": "^6.0",
27+
"symfony/finder": "^6.0",
28+
"symfony/event-dispatcher": "^6.0",
29+
"symfony/dependency-injection": "^6.0",
30+
"symfony/dom-crawler": "^6.0",
31+
"symfony/css-selector": "^6.0",
32+
"symfony/console": "^6.0",
33+
"symfony/http-client": "^6.0",
34+
"symfony/string": "^6.0",
35+
"twig/twig": "^3.3",
36+
"twig/string-extra": "^3.6"
2937
},
3038
"require-dev": {
31-
"gajus/dindent": "^2.0",
32-
"symfony/phpunit-bridge": "^5.2 || ^6.0 || ^7.0",
33-
"symfony/process": "^5.2 || ^6.0 || ^7.0",
34-
"masterminds/html5": "^2.7"
39+
"league/flysystem-memory": "^3.0",
40+
"symfony/phpunit-bridge": "^7.4@dev",
41+
"symfony/process": "^6.0",
42+
"symfony/var-dumper": "^6.2"
3543
},
36-
"bin": ["bin/docs-builder"]
44+
"scripts": {
45+
"test": "SYMFONY_PHPUNIT_VERSION=12 simple-phpunit",
46+
"psalm": [
47+
"composer update --no-scripts --working-dir=tools/psalm",
48+
"./tools/psalm/vendor/bin/psalm"
49+
],
50+
"cs": [
51+
"composer update --no-scripts --working-dir=tools/php-cs-fixer",
52+
"./tools/php-cs-fixer/vendor/bin/php-cs-fixer fix"
53+
]
54+
}
3755
}

‎config/parser.php‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the Docs Builder package.
5+
*
6+
* (c) Ryan Weaver <[email protected]>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Symfony\Component\DependencyInjection\Loader\Configurator;
13+
14+
use phpDocumentor\Guides\RestructuredText\Parser\Productions\DirectiveContentRule;
15+
use phpDocumentor\Guides\RestructuredText\TextRoles\TextRole;
16+
17+
return static function (ContainerConfigurator $container) {
18+
$container->services()
19+
->defaults()->autowire()
20+
21+
->load('SymfonyDocsBuilder\\Directives\\', '../src/Directives')
22+
->bind('$startingRule', service(DirectiveContentRule::class))
23+
->tag('phpdoc.guides.directive')
24+
25+
->load('SymfonyDocsBuilder\\TextRole\\', '../src/TextRole')
26+
->tag('phpdoc.guides.parser.rst.text_role')
27+
;
28+
};

‎config/renderer.php‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the Docs Builder package.
5+
*
6+
* (c) Ryan Weaver <[email protected]>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Symfony\Component\DependencyInjection\Loader\Configurator;
13+
14+
use SymfonyDocsBuilder\Highlighter\SymfonyHighlighter;
15+
use SymfonyDocsBuilder\NodeRenderer\CodeNodeRenderer;
16+
use SymfonyDocsBuilder\NodeRenderer\MenuEntryRenderer;
17+
use SymfonyDocsBuilder\Node\ExternalLinkNode;
18+
use SymfonyDocsBuilder\Twig\CodeExtension;
19+
use SymfonyDocsBuilder\Twig\UrlExtension;
20+
use Twig\Extension\ExtensionInterface;
21+
use Twig\Extra\String\StringExtension;
22+
use phpDocumentor\Guides\Code\Highlighter\Highlighter;
23+
use phpDocumentor\Guides\NodeRenderers\NodeRenderer;
24+
use phpDocumentor\Guides\NodeRenderers\TemplateNodeRenderer;
25+
26+
return static function (ContainerConfigurator $container) {
27+
$container ->services()
28+
->defaults()->autowire()->autoconfigure()
29+
->instanceof(ExtensionInterface::class)->tag('twig.extension')
30+
->instanceof(NodeRenderer::class)->tag('phpdoc.guides.noderenderer.html', ['priority' => 10])
31+
32+
->set(CodeExtension::class)
33+
->set(UrlExtension::class)
34+
->set(StringExtension::class)
35+
36+
->set(CodeNodeRenderer::class)
37+
->set(MenuEntryRenderer::class)
38+
39+
->set('symfony.node_renderer.html.inline.external_link', TemplateNodeRenderer::class)
40+
->arg('$template', 'inline/external-link.html.twig')
41+
->arg('$nodeClass', ExternalLinkNode::class)
42+
43+
->set(SymfonyHighlighter::class)
44+
->decorate(Highlighter::class)
45+
;
46+
};

‎config/services.php‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the Docs Builder package.
5+
*
6+
* (c) Ryan Weaver <[email protected]>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Symfony\Component\DependencyInjection\Loader\Configurator;
13+
14+
use Psr\EventDispatcher\EventDispatcherInterface;
15+
use SymfonyDocsBuilder\Build\BuildConfig;
16+
use SymfonyDocsBuilder\DocBuilder;
17+
use Symfony\Component\Console\Output\ConsoleOutput;
18+
use Symfony\Component\EventDispatcher\EventDispatcher;
19+
20+
return static function (ContainerConfigurator $container) {
21+
$container->services()
22+
->defaults()->autowire()
23+
24+
->set(EventDispatcherInterface::class, EventDispatcher::class)
25+
26+
->set(BuildConfig::class)
27+
28+
->set(DocBuilder::class)->public()
29+
;
30+
};

‎phpunit.xml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3+
xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/12.4/phpunit.xsd"
4+
bootstrap="vendor/autoload.php"
5+
beStrictAboutOutputDuringTests="true"
6+
failOnDeprecation="true"
7+
failOnRisky="true"
8+
failOnWarning="true"
9+
cacheDirectory=".phpunit.cache"
10+
beStrictAboutCoverageMetadata="true">
11+
<testsuites>
12+
<testsuite name="default">
13+
<directory>tests</directory>
14+
</testsuite>
15+
</testsuites>
16+
17+
<source ignoreSuppressionOfDeprecations="true"
18+
ignoreIndirectDeprecations="true"
19+
restrictNotices="true"
20+
restrictWarnings="true">
21+
<include>
22+
<directory>src</directory>
23+
</include>
24+
25+
<deprecationTrigger>
26+
<function>trigger_deprecation</function>
27+
<method>Doctrine\Deprecations\Deprecation::trigger</method>
28+
<method>Doctrine\Deprecations\Deprecation::delegateTriggerToBackend</method>
29+
</deprecationTrigger>
30+
</source>
31+
</phpunit>

‎psalm.xml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<?xml version="1.0"?>
2+
<psalm
3+
errorLevel="2"
4+
resolveFromConfigFile="true"
5+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
6+
xmlns="https://getpsalm.org/schema/config"
7+
xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
8+
findUnusedCode="false"
9+
findUnusedBaselineEntry="true"
10+
>
11+
<projectFiles>
12+
<directory name="src" />
13+
<directory name="config" />
14+
<ignoreFiles>
15+
<directory name="vendor" />
16+
</ignoreFiles>
17+
</projectFiles>
18+
19+
<issueHandlers>
20+
<ImplicitToStringCast errorLevel="suppress" />
21+
</issueHandlers>
22+
</psalm>

‎resources/highlight.php/README.md‎

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

0 commit comments

Comments
 (0)