Godot-docs: Overridden properties should link to parent property definition

[joshdegraw]

Your Godot version: Latest Docs

Issue description: Override properties currently don't link to the highest level parent property that they're overriding. While this isn't a huge problem, I believe this would be a nice change that would make finding information faster while not cluttering every page with a redefinition. I believe a hyperlink (or something similar) for that property that links to the property section of the parents' page would be an elegant solution.

URL to the documentation page (if already existing): Example: https://docs.godotengine.org/en/latest/classes/class_checkbox.html?highlight=checkbox
CheckBox is overriding both "align" and "toggle_mode" with its own default value, and a hyperlink (or something similar) would allow me to see how Button and BaseButtom (respectively) define those properties.

[pycbouh]

I agree and suggested as much the last time this part of the doc generation was touched. I think this is doable.

It requires modifying quite a few components in our system, though.

• The basis for all docs is XML files on the main repo.
• The XMLs are generated with C++ code, using the Godot executable in doctool mode. The relevant code starts here and relies on DocTools class. Look for the places that work with the overridden property.
• The online docs first need to be converted into RSTs, this script is used.

A bit more information on how to use the doctool.

[joshdegraw]

In order to implement this, it looks like the XML generator will need to be updated first to contain new information. For example, if you look at this line:
https://github.com/godotengine/godot/blob/d834789f475d431b10dcaef8804cd75dcd8b47dd/doc/classes/CheckBox.xml#L15
The method keeps a bool if it's an override or not. This should probably be a reference to the class where it is defined, such as this line:
https://github.com/godotengine/godot/blob/d834789f475d431b10dcaef8804cd75dcd8b47dd/doc/classes/CheckBox.xml#L2
Since doctool is already doing work to figure out if the method is overridden or not, I hope it won't be too difficult. I'm currently looking at doctool and will report back some time tomorrow (I am heading to bed soon).
Thanks for pointing me in the right direction, everyone.

[joshdegraw]

The best solution that I could think of was to loop through parents until the property is found that wasn't inherited in the generate() function. This required adding another field to PropertyDoc since the editor currently relies on the overridden bool in a way that makes sense for it to be a bool (we can revisit this?), and trying to do it when writing the XML seems out of scope for the save_classes method.
Here's the CheckBox example with the new XML:
https://github.com/joshdegraw/godot/blob/afd105a074817dcf8db112729a8bd9c46aa7fbf3/doc/classes/CheckBox.xml#L15

If we like this implementation, I will begin modifying the Python to hyperlink to the correct page.

[Calinou]

@joshdegraw Can you push your C++ code to a fork and link to it? This would be greatly appreciated :slightly_smiling_face:

You can also open a pull request on the main Godot repository and mark it as a draft. Make sure to open the pull request against the master branch (which is where feature development happens), not 3.2.

[pycbouh]

@Calinou I think they did push and link it already in the message above 🙃 https://github.com/joshdegraw/godot/commit/afd105a074817dcf8db112729a8bd9c46aa7fbf3

Namely this is the gist of it: https://github.com/joshdegraw/godot/blob/afd105a074817dcf8db112729a8bd9c46aa7fbf3/editor/doc_tools.cpp#L288

@joshdegraw btw, I recommend installing pre-commit hooks to make sure your code complies with the style rules we have on the main repo.
https://github.com/joshdegraw/godot/tree/master/misc/hooks

[joshdegraw]

Created a draft pull request: https://github.com/godotengine/godot/pull/44187

I will be adding new updates to the pull request.