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

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)

src/GuidesExtension/src/Application.php

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

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?

It would be nice for a fully compatible fjson renderer, but it's not a blocker for Symfony adaption as far as I can see (as we don't use the parent data).

As long as this renderer is in this repo (rather than being submitted upstream), it is not an issue if it does not support full compatibility with Sphinx (it might make sense to document the known differences though, for easier maintenance).

wouterj · 2026-03-24T22:56:33Z

Sooo, I've managed to hack this version of the DocsBuilder into the symfony.com repository. It's not nice yet, but it somewhat works.

As an example, let's take https://symfony.com/doc/8.1/quick_tour/the_architecture.html Locally with phpDocumentor Guides, this now renders like this: https://github.com/user-attachments/assets/da0d8b1f-7b5b-44ce-97df-4d5df05cd390

Comparing this with the live version, pixel by pixel, the only differences are found in the diff code blocks. And the phpDocumentor variant is actually more correct!

I've updated the JSON tests to represent the actual data we need: we need a lot of TOC information that I forgot to implement. Also, I want to refactor things a bit to merge BuildEnvironment and BuildConfig, and ideally avoid defining either as a service.

We also need better reporting on failures in DocBuilder, so we can make the build error/warning log working.

But, this is looking very promising!

stof reviewed Dec 1, 2025

View reviewed changes

src/GuidesExtension/src/Application.php Show resolved Hide resolved

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 5 commits March 20, 2026 15:01

Upgrade to Symfony 8

a89dc29

Add support for tabs directive

b10f781

Require PHPUnit directly

ccb5737

Upgrade Guides to fix the testBlocks@nodes/title.rst test

cfbc874

Update JsonRenderer tests based on real integration

dcc64af

Use relative references

3f57237

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!

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!

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 commented Mar 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

wouterj commented Nov 30, 2025 •

edited

Loading

wouterj commented Mar 16, 2026 •

edited

Loading