phpDocumentor Guides integration by wouterj · Pull Request #200 · symfony-tools/docs-builder

wouterj · 2025-11-30T20:04:10Z

This merges the SymfonyExtension from https://github.com/wouterj/symfony-docs-guides into this project.

Todo

Add fjson output support (Implement JSON builder wouterj/symfony-docs-guides#8)
Add missing tabs directive (preferably, in phpDocumentor: Move tabs/tab directive to rst package phpDocumentor/guides#1316)
Upgrade to PHP 8.5 and Symfony 8 (requires Fix registering a service from another sub-package phpDocumentor/guides#1317)
Improve asset handling in phpDocumentor so we can store images and docs separately (symfony.com requirement). I have an idea for this, but no code yet.
Make a working prototype in the symfony.com repository, probably requires some updates to the DocsKernel and DocBuilder in this repository
Restore license/copyright data where applicable
Cleanup this repository, removing Doctrine RST Parser related code. Also: discuss if we want to retain functionality like PDF generation, link checking.

stof · 2025-12-01T13:48:29Z

src/Application.php

 /*
- * This file is part of the Docs Builder package.
- * (c) Ryan Weaver <ryan@symfonycasts.com>
+ * This file is part of the Guides SymfonyExtension package.


This looks wrong to me.

src/TextRole/ClassRole.php

resources/highlight.php/php.json

composer.json

src/Application.php

stof · 2025-12-01T13:56:50Z

src/GuidesExtension/src/Build/StringBuildEnvironment.php

+        $this->filesystem->put('index.rst', $contents);
+    }
+
+    #[\Override]


we don't use this attribute in Symfony (and Psalm has a config setting to avoid requiring its usage)

stof · 2025-12-01T14:33:34Z

src/GuidesExtension/src/Application.php

-    {
-        $this->application = new BaseApplication();
-        $this->buildConfig = new BuildConfig();
+    public function __construct(


This change breaks the bin/docs-builder script currently.

@javiereguiluz is the symfony.com website using the docs-builder executable or is it using this package as a library ?

We use it as a library

Could you share the integration code ? It would make it easier to figure out how to avoid (or at least reduce) BC breaks.

For full docs (Symfony Docs, bundles, the Symfony Book) it's basically this:

$buildConfig = (new BuildConfig()) ->setContentDir($buildDir) ->setOutputDir($tempBuildDir) ->setImagesDir($publicImagesDir) ->setImagesPublicPrefix($publicImagesPrefix); if ('symfony' === $bookSlug) { $buildConfig->setSymfonyVersion($branch); } try { $result = $this->docBuilder->build($buildConfig); if (!$result->isSuccessful()) { // ... } } catch (\Throwable $e) { // ... }

For blog posts, it's just this:

$parseResult = (new DocBuilder())->buildString($rstContents); if (!$parseResult->isSuccessful()) { // ... }

@wouterj this means it would be great to revert changes done to the DocBuilder public API if possible (I think we could expose the same public API than today based on top of guides) as it is the public API of this library.

Note that I don't even see where your new code uses the modified DocBuilder API (except in tests that haven't been updated and so are failing)

Yes yes. I now also have access to the code behind the symfony.com's docs rendering. So I've started working on the integration (and making the new SymfonyExtension installable is a big part of that). Small steps, but we'll get there :)

wouterj · 2025-12-01T15:06:38Z

Thanks for the detailed review, @stof :)

This was just a blunt import of the commits I made in my test project, which I started from scratch. So the goal now is to make sure the code in this PR matches whatever we were doing in this repository before. Your comments are a great start with this, as they show some unintentionally difference that we should revert from this PR before merging.

stof · 2025-12-01T15:16:49Z

The CI also tells me that existing tests must be updated (which will help avoiding regressions if they can still run)

This will help differentiating between the Doctrine RST parser based code and phpDocumentor Guides based code for now. Once everything is cleaned up, we can flatten the structure again.

wouterj · 2026-03-16T11:09:31Z

Little update after this weekend: I've applied the changes applied to this repository since starting with the guides one 2 years ago (like AI github links and code highlight changes).

I've also merged the integration test fixtures from the Guides integration and this repository. This allows you to see the differences in the output, although 99% of it is whitespace so it's very hard to review. While working on the integration, I've been very careful with updating the expected files so I'm very confident the resulting HTML is still equal.

Next up: moved to PR description

javiereguiluz · 2026-03-16T11:14:22Z

Wouter, thanks a lot for the detailed update and for all this work!

tests/fixtures/expected/blocks/directives/caution.html

stof · 2026-03-17T15:48:47Z

src/GuidesExtension/src/DocBuilder.php

+use SymfonyTools\DocsBuilder\GuidesExtension\Build\BuildEnvironment;
+use SymfonyTools\DocsBuilder\GuidesExtension\Build\StringBuildEnvironment;
+
+final class DocBuilder


shouldn't this DocBuilder class stay outside the GuidesExtension namespace ? This looks like the entrypoint using guides more than an extension of the guides library.

Yes, for now (to easily differentiate between new and old code), I've moved everything in the GuidesExtension. But some of it will be moved back once the repository is cleaned up.

stof · 2026-03-17T15:51:30Z

composer.json

    "autoload": {
        "psr-4": {
+            "SymfonyTools\\DocsBuilder\\GuidesExtension\\": "src/GuidesExtension/src",
            "SymfonyDocsBuilder\\": "src"


is this SymfonyDocsBuilder namespace still used ?

composer.json

stof · 2026-03-17T15:53:06Z

composer.json

    },
-    "bin": ["bin/docs-builder"]
+    "scripts": {
+        "test": "SYMFONY_PHPUNIT_VERSION=12 simple-phpunit",


I would suggest moving away from this simple-phpunit in favor of installing phpunit/phpunit as a dev requirement, which is the recommended approach for modern Symfony projects now.
It only involves registering the SymfonyExtension explicitly in the phpunit.xml file.

Interesting, I thought we wanted to keep using simple-phpunit for libraries (especially by the Symfony team itself). But I see UX is using simple-phpunit, whereas AI is using phpunit. So we probably do not have a strict guideline on this

We use simple-phpunit in the main mono-repo because of its built-in parallelization of tests per sub-package, that is quite specific to the structure of the main mono-repo.
For other projects, the simple-phpunit script does not provide much benefit anymore. It only makes it harder to control which version of PHPUnit is used and to ensure you don't have conflicting versions of dependencies installed (reduced risk as phpunit reduced its dependencies outside phpunit/* and sebastian/*, but not void as some other packages also reuse sebastian/*).
For this case, installing phpunit as a dev requirement is simpler.

wouterj · 2026-03-17T22:13:33Z

tests/fixtures/source/json/orphan.rst

@@ -1,3 +1,5 @@
+:orphan:
+


! orphaned documents are not automatically detected

(probably not a major blocker: symfony.com only renders Prev/Next page links for very specific sections of the docs)

wouterj · 2026-03-17T22:14:52Z

src/GuidesExtension/src/Renderer/JsonRenderer.php

+            $context->getDestination()->put(
+                $context->getDestinationPath().'/'.$context->getCurrentFileName().'.fjson',
+                json_encode([
+                    'parents' => [],


No easy support for fetching the parent document. As far as I can find the symfony.com code, this property is never used so probably safe to ignore (cc @javiereguiluz please double check my assumption 😄)

@wouterj would a proper document tree in phpDocumentor/guides help?

stof reviewed Dec 1, 2025

View reviewed changes

wouterj mentioned this pull request Mar 1, 2026

Upgrade to guides #202

Closed

wouterj added 21 commits March 14, 2026 16:00

Convert docs builder into an extension

8e290fe

Cleanup

21ef959

Update to latest Guides

78614b5

Upgrade to latest guides and use guides-code's highlighter

b4d3554

Fix SymfonyExtension build

f1974c7

Set-up Psalm CI

cbc1362

Set-up PHP CS Fixer CI

2f8a2c7

Use guides-code from Packagist

908a935

Upgrade to Sphinx RTD Theme 2.0.0

a051171

Unskip fixed test cases

fb8c2e8

Upgrade Guides and split RTD theme

d0251f1

Do not use anchors for document links in toctree

2c41ce3

Enable toctree project test

74ff68b

Fix CI

91c3ded

Fix CS

262f58f

Upgrade to Guides 1.0

016b7fc

Made last skipped test green

d4b9c30

Upgrade to latest Guides

d8b8547

Upgrade other dependencies

e2a9ed5

Apply recent changes to DocsBuilder in new code

388cc64

Move GuidesExtension code into a subdirectory

5cfd812

This will help differentiating between the Doctrine RST parser based code and phpDocumentor Guides based code for now. Once everything is cleaned up, we can flatten the structure again.

wouterj force-pushed the phpdocumentor-guides branch from bf5952b to fa579ee Compare March 15, 2026 14:40

wouterj added 3 commits March 15, 2026 15:44

Merge integration tests

516d502

Replace version placeholder with Symfony version in URLs

aebc39f

Use newer PHPUnit version in GitHub Workflow

1682f32

wouterj force-pushed the phpdocumentor-guides branch from 86ae537 to 1682f32 Compare March 15, 2026 14:44

wouterj added 2 commits March 15, 2026 23:53

Fix php class role with namespaced FQCN

b6730bd

Skip non-html integration tests

5096197

wouterj commented Mar 16, 2026

View reviewed changes

tests/fixtures/expected/blocks/directives/caution.html Outdated Show resolved Hide resolved

stof reviewed Mar 17, 2026

View reviewed changes

wouterj added 3 commits March 17, 2026 22:14

Update caution icon

fedc9d7

Fix highlightphp tests

1bf4f75

Add fjson renderer

060aa2a

wouterj mentioned this pull request Mar 17, 2026

Implement JSON builder wouterj/symfony-docs-guides#8

Closed

wouterj commented Mar 17, 2026

View reviewed changes

wouterj added 2 commits March 20, 2026 15:01

Upgrade to Symfony 8

a89dc29

Add support for tabs directive

b10f781

Conversation

wouterj commented Nov 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Todo

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wouterj Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wouterj commented Dec 1, 2025

Uh oh!

stof commented Dec 1, 2025

Uh oh!

wouterj commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

javiereguiluz commented Mar 16, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

wouterj commented Nov 30, 2025 •

edited

Loading

wouterj Dec 1, 2025 •

edited

Loading

wouterj commented Mar 16, 2026 •

edited

Loading