Skip to content
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

Resolve collisions in reference anchors added for methods #84618

Conversation

YuriSizov
Copy link
Contributor

While the anchors themselves were sufficiently unique, when converted to HTML all underscore characters are replaced. This created collisions between, say, Object._get and Object.get, where the latter would get a generic unique anchor identifier, e.g. id1.

You can test this yourself in the current version of the online documentation: https://docs.godotengine.org/en/stable/classes/class_object.html

Now, this change will break existing links in the online docs, which need to be fixed manually after the class reference is synced. It will also break public-facing links for the affected methods, but will allow us to properly link methods which currently get their anchor ids replaced.


Here's a diff from these changes compared to the base commit:
rst-changes.zip

While the anchors themselves were sufficiently unique,
when converted to HTML all underscore characters are
replaced. This created collisions between, say, Object._get and
Object.get, where the latter would get a generic unique
anchor identifier, e.g. id1.
@YuriSizov YuriSizov added this to the 4.2 milestone Nov 8, 2023
@YuriSizov YuriSizov requested a review from a team as a code owner November 8, 2023 14:23
@akien-mga
Copy link
Member

Adding private for methods starting with _ seems a bit weird to me, as most of those aren't private but virtual.

How about not removing leading underscores for the HTML-ification? So we'd get:

https://docs.godotengine.org/en/stable/classes/class_object.html#class-object-method-_get
https://docs.godotengine.org/en/stable/classes/class_object.html#class-object-method-get
https://docs.godotengine.org/en/stable/classes/class_object.html#class-object-method-_property-get-revert
https://docs.godotengine.org/en/stable/classes/class_object.html#class-object-method-property-get-revert

@YuriSizov
Copy link
Contributor Author

those aren't private but virtual.

Technically they are both, which is why I went for private as a more all-encompassing option. You are not expected to call them from the outside (at least in userland).

How about not removing leading underscores for the HTML-ification?

This happens somewhere in Sphinx, I don't think we have much control over it.

@akien-mga akien-mga merged commit e769a75 into godotengine:master Nov 9, 2023
15 checks passed
@akien-mga
Copy link
Member

Thanks!

@YuriSizov YuriSizov deleted the docs-resolve-method-reference-collisions branch November 9, 2023 11:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants