Skip to content

Commit ccb4f60

Browse files
authored
[TASK] guides.xml: inventory slash, extension class, theme attr (#545)
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>
1 parent 18c266b commit ccb4f60

1 file changed

Lines changed: 16 additions & 0 deletions

File tree

Documentation/Reference/GuidesXml.rst

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,13 @@ And follow the interactive question.
5050

5151
The following settings can be relevant for TYPO3 themed documentation:
5252

53+
.. note::
54+
The schema accepts a :xml:`theme` attribute on :xml:`<guides>`,
55+
but TYPO3 documentation does not need it: the theme is loaded by
56+
the :xml:`<extension class="...Typo3DocsThemeExtension">` tag. A
57+
:xml:`<theme>` **child element** is invalid and aborts rendering
58+
with `Invalid type for path guides.theme`.
59+
5360
.. _settings-guides-default-code-language:
5461

5562
.. confval:: default-code-language
@@ -137,6 +144,9 @@ And follow the interactive question.
137144
138145
<inventory id="sphinx" url="https://www.sphinx-doc.org/en/master/"/>
139146
147+
The :xml:`url` should end with a trailing slash (:xml:`.../en-us/`) —
148+
without it, resolving the inventory can fail.
149+
140150

141151
.. _settings-guides-project:
142152

@@ -242,6 +252,12 @@ And follow the interactive question.
242252
The class attribute is mandatory, it references the extension that is used
243253
to render the documentation with the TYPO3 documentation theme.
244254

255+
.. note::
256+
If the :xml:`class` attribute (or the whole :xml:`<extension>`
257+
tag) is missing, the documentation renders with the default
258+
phpDocumentor layout instead of the TYPO3 theme. No error is
259+
raised — the output just looks wrong.
260+
245261
.. _settings-guides-github-workflow:
246262

247263
.. confval:: edit-on-github-*

0 commit comments

Comments
 (0)