Conversation
|
This PR is more like "compatibility" glue, in comparison, but it may be redundant if we end up replacing all pseudo-admonitions in the future either way. |
|
Thanks for pointing that out! I agree the default admonitions are definitely on the big side especially when there are several in sequence. The PRs you linked sound like they tackle the problem well and have good approval, so I'll close this PR for now and put my support behind those ones instead. |
|
Mind you, I'm not necessarily dismissing this PR. A similar idea may even be the better option in the near future because a full replacement (for translations, too) is a big undertaking (but we've done it before) |
|
Alright, I will re-open it then just in case, but still see what I can do to support the other PR. Thank you for the clarification 😄 |
|
Do feel free to use the regex I mentioned in #111375, as it also includes Once #111375 is merged, and if/when we decide the new "classref admonitions" are the way to go, we'll need to ask contributors to start using the new format as well. |
In the long run, the spots where these show up in the XML documentation should be moved from [b]Note:[/b] to [note] and so on. But for now, this should convert the existing ones to the new appearance.
1c6416d to
b02283f
Compare
What problem(s) does this PR solve?
I thought I'd remembered writing a proposal for this some time ago, but couldn't find it tonight (or another proposal that matches it). If need be I can write a proposal for it soon, to go alongside this PR.
Additional information
This PR adds an extra processing step to the conversion from the XML class reference files to RST documents, so that
[b]Note:[/b]and[b]Warning:[/b]blocks are now placed in admonition blocks ([note],[warning], etc). These help them stand out more to readers (especially important for warnings).Note that localization is not currently supported; as you can see in the PR changes, the strings "Note:" and "Warning:" are hardcoded. I don't think that this should break anything in localized versions - they should just appear the same as before. But for this to support localized versions of the class reference, we'll need to find the corresponding strings in each language and replace them in the regex pattern here.