Add a custom role to toggle between snake_case and PascalCase syntax #4406
Conversation
|
I would suggest renaming it to "GDScript Code Examples" and "C# Code Examples" otherwise some people may be confused that those too can be used interchangeably in thier code. |
I've considered naming the options "GDScript" and "C#" instead of "snake_case" and "PascalCase", but there is no 1:1 mapping between syntax styles and languages. For instance, if you use GDNative or a C++ module, you're going to use snake_case. |
|
Maybe then add |
There's already a tooltip for each option telling you which languages each syntax is used in. I think that's enough 🙂 |
|
Okay that's fair. |
Calinou
force-pushed
the
add-snake-pascal-toggle
branch
from
a76cd68 to
2671ca8
Compare
…yntax TODO: - See whether we can associate data attributes in Sphinx to avoid reflows during page load and have correct display when JavaScript is disabled. - Modify `doc/tools/makerst.py` to take this role into account. - Test automatic conversion rules in more real-world scenarios. It probably involves testing in production due to the amount of documentation :)
Calinou
force-pushed
the
add-snake-pascal-toggle
branch
from
2671ca8 to
cb7212f
Compare
|
Now that we updated Maybe we can
And while its indeed not a perfect or correct mapping, I'm somewhat leaning towards labelling it 'GDscript/C#' too, may be less confusing to new users while those who know C++ etc. will still likely know what to do/press? Edit: besides this discussion, love this work :) Way less mental overhead for me as a C# user! |
|
I like this a lot! I think it could potentially be a good foundation for dividing the docs across different languages. Though, I think having language specific tabs would be more intuitive and scalable than the writing style tabs. Overall, I think this is a fantastic stepping stone. Now, how would we proceed on populating the docs with C# counterparts to start with, using this? |
YuriSizov
added
the
content:website
snake_case is still used by default, but the user can switch to PascalCase if they use C#. This choice is persisted to the browser's localStorage. This helps decrease the cognitive load for C# users when reading the documentation.
Class reference links have their link text changed automatically to match the user's preference.
Inline code literals have to be converted manually to account for special cases. (Sometimes, going from GDScript to C# involves more than just changing the casing from snake_case to PascalCase.)
Preview
TODO
editor/editor_help.cppto understand the[snakepascal]snake_case;;PascalCase[/snakepascal]tag.doc/tools/makerst.pyto generate:snakepascal:roles from[snakepascal]blocks.