Tweak reference documents #20712
Merged
Tweak reference documents #20712
+0
−15
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
stof
approved these changes
Mar 3, 2025
|
Don't we now have to replace |
|
@xabbuh no ... because reStructuredText allows many different markers for section titles and doesn't impose any specific order. The first marker found is considered h1, the second different marker found in the document is considered h2, etc. See https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#sections For consistency, we could update this ... but it's going to be a nightmare to merge into upper branches 😓 I built the docs locally to double check that our tooling supports this, and it looks like it does:
|
xabbuh
approved these changes
Mar 3, 2025
|
The new TOC makes so much sense and makes this page way clearer. It was always hard to find elements on it. Thank you, this is a HUGE improvement! |
javiereguiluz
added a commit
that referenced
this pull request
Mar 4, 2025
…iluz) This PR was merged into the 7.2 branch. Discussion ---------- [Reference] Sort debug options alphabetically Sorting the options of Configuration Reference was always important ... but after #20712 this is even more important. There are only two documents to sort: `debug` and `framework`. This PR updates the first one, which is trivial. But fixing `framework` will take a lot of effort (and would be a merge conflict nightmare). That's why I propose to do this only in 7.2 branch and up. Commits ------- 569f548 [Reference] Sort debug options alphabetically
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
As reported by @stof, there's a problem with some Configuration Reference documents.
Problem
h4andh5headings are styled the same on symfony.comThis makes hard to understand options like this: https://symfony.com/doc/current/reference/configuration/framework.html#not-compromised-password
enabledandendpointare sub-keys ofnot_compromised_passwordwhilestatic_methodis a sibling. Very confusing.Solution
I don't want to make
h5even smaller or different in any way. I think that needing to useh5reveals a complexity problem in your page.So, let's fix this differently. And I think there could be a very simple solution.
Look at the page TOC:
The "useless"
Configurationtitle adds a heading level in the entire page, pushing some elements toh5level. If we remove it, all the sub-headings go up one level automatically. This will probably be enough.Note that the perfect solution would be to remove
Configurationheading and update ALL the other headings to use the same heading markers (---,~~~, etc.) as the rest of Symfony Docs.Doing this would be a merge conflict nightmare. Luckily, reStructuredText format doesn't care about the specific markers used. The first one it finds is h2, the second one is h3 and so on. So, I think it's fine to use different markers just on these reference pages.
what do you think?