-
-
Notifications
You must be signed in to change notification settings - Fork 21.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add code sample language parity check to make_rst.py
#86971
Conversation
I love this, I think it can be very helpful. Although I think the bigger problem is that the C# example exists but is outdated.
C# types with notable differences are listed in in The problem with these types is that often the methods themselves have a different name or are in a completely different type, so adding an example under a function named after Core/GDScript will look weird. For example, the Array type has an This is one of the reasons why users ask for a dedicated C# class reference (see godotengine/godot-docs#6596). I don't want to go too off-topic, I just wanted to illustrate that this is a complicated issue so I think it may be reasonable to exclude Variant types. These types are documented in the C# source code. |
Makes sense. What do we want to do with |
All Variant types are manually defined in C# or use a BCL type except for Object which is partially generated. Object is called Some of the Variant types, even though they are manually defined, don't differ too much form Core's API. In general, if the Variant type is not listed in For the parity check we can just exclude all Variants except Object. I think that'd be good enough so we don't have to maintain a list.
I don't know. I don't mind including C# samples even if they look a bit odd and aren't very discoverable, I just wouldn't make it a requirement. Specially if this parity check is enforced in CI in the future. |
This is going to be very useful, thanks 🙏 |
e3054e1
to
cb136c5
Compare
Removed all Variant types except for 176 code samples failed parity check. Use --verbose to get more information
|
cb136c5
to
bba3c70
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks great to me! Makes sense to keep track of this.
make_rst.py
Thanks! |
This adds a non-blocking validator to
make_rst.py
which can report if codeblocks are missing parity between GDScript and C# samples. It's greedy and only ignores global contexts (which are basically GDScript-only methods). We may want to exclude Variant types as well, but I'm not confident that we should. There are differences in those types, but they should probably still be documented with correct samples. cc @raulsntos though.The report is shallow by default:
But using the new
--verbose
flag you can see it in its entirety:Here's how it looks colorized:
The purpose of this is to provide a tool for documentation contributors to quickly find pieces of the docs missing C# samples. I don't think this is something we can currently enforce on the CI, but maybe one day, after increasing completion and adjusting the settings of this validator.
Inspired by Juan's tweet from a few days ago.