From d0cd7fa5021234f6d3c4e341a68024f25f4b43b6 Mon Sep 17 00:00:00 2001
From: Sebastian Mendel <github@sebastianmendel.de>
Date: Fri, 14 Aug 2026 14:43:42 +0200
Subject: [PATCH] [TASK] guides.xml: inventory slash, extension class, theme
 attr

Three additions from observed failures: inventory URLs should end
with a trailing slash; a missing extension class silently falls
back to the default phpDocumentor layout (no error raised); the
schema-valid theme attribute is not needed (the theme comes from
the extension class) while a theme child element aborts rendering
with 'Invalid type for path guides.theme'.

Assisted-by: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
---
 Documentation/Reference/GuidesXml.rst | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/Documentation/Reference/GuidesXml.rst b/Documentation/Reference/GuidesXml.rst
index b00d0687..f6cac058 100644
--- a/Documentation/Reference/GuidesXml.rst
+++ b/Documentation/Reference/GuidesXml.rst
@@ -50,6 +50,13 @@ And follow the interactive question.
 
         The following settings can be relevant for TYPO3 themed documentation:
 
+        ..  note::
+            The schema accepts a :xml:`theme` attribute on :xml:`<guides>`,
+            but TYPO3 documentation does not need it: the theme is loaded by
+            the :xml:`<extension class="...Typo3DocsThemeExtension">` tag. A
+            :xml:`<theme>` **child element** is invalid and aborts rendering
+            with `Invalid type for path guides.theme`.
+
         ..  _settings-guides-default-code-language:
 
         ..  confval:: default-code-language
@@ -137,6 +144,9 @@ And follow the interactive question.
 
             <inventory id="sphinx" url="https://www.sphinx-doc.org/en/master/"/>
 
+        The :xml:`url` should end with a trailing slash (:xml:`.../en-us/`) —
+        without it, resolving the inventory can fail.
+
 
     ..  _settings-guides-project:
 
@@ -242,6 +252,12 @@ And follow the interactive question.
         The class attribute is mandatory, it references the extension that is used
         to render the documentation with the TYPO3 documentation theme.
 
+        ..  note::
+            If the :xml:`class` attribute (or the whole :xml:`<extension>`
+            tag) is missing, the documentation renders with the default
+            phpDocumentor layout instead of the TYPO3 theme. No error is
+            raised — the output just looks wrong.
+
         ..  _settings-guides-github-workflow:
 
         ..  confval:: edit-on-github-*