Additional Cross-Linking

[ArsThaumaturgis]

The manual, I believe, links to the API in places: in some cases a mention of a class will link to the API page for that class.

What I'd like to suggest is that this be more extensive: That any mention of a class-name (in the manual or API) link to the API reference to that class. That, in short, the documentation work a bit like TVTropes.

This, I feel, might make it easier to traverse the documentation, and thus to find desired information. If one wants to check on a class that has just been mentioned--perhaps as a return-value from a method, or referenced in passing in the manual--one can click through immediately, without having to manually search.

(I would imagine this being automated, with class-names being picked out and linked by code; doing this manually seems tedious and prone to omissions!)

[rdb]

In the manual, I think this just means replacing any reference to a class with :class:`.ClassName` in the manual. I've been doing that as much as possible, but I'll always miss cases. This is something that others can help with by contributing PRs with these types of replacements.

As for the API reference, I purposefully didn't just replace any word that matched a class or method name. For example, a method with description "Notify this system that something happened." would match Notify as a class name unintentionally.

Maybe I can apply the rule for classes with at least two capital letters (eg. NodePath), since that isn't likely to match any normal English word.

[ArsThaumaturgis]

In the manual, I think this just means replacing any reference to a class with :class:`.ClassName` in the manual. I've been doing that as much as possible, but I'll always miss cases. This is something that others can help with by contributing PRs with these types of replacements.

That's good to read! ^_^

As for the API reference, I purposefully didn't just replace any word that matched a class or method name. For example, a method with description "Notify this system that something happened." would match Notify as a class name unintentionally.

Maybe I can apply the rule for classes with at least two capital letters (eg. NodePath), since that isn't likely to match any normal English word.

Ah, that's fair. Hmm... Could you perhaps set a rule that replaces class-names in parameter/return data? That data should be fairly unlikely to include such collisions, and would be a rather useful place to have cross-links between classes, I feel.

[rdb]

I've been adding more cross-links and just did an extensive pass through the first part of the manual to add cross-links to the API reference (as well as making other fixes). I've done up to and including the Sound section, but phoo, this is tedious work. It may help to first address #74 before continuing so that creating references is less work, and in fact, I would be in favour of allowing direct references to `base.thing` and `loader.loadModel` and having those be automatically understood as referring to ShowBase and Loader, respectively (so we don't have to type things like :py:obj:`base.musicManager <direct.showbase.ShowBase.ShowBase.musicManager>` ).

In the API reference docstrings, anything that looks like a class name or method is now also automatically converted to a link.

Furthermore, any cross-links to C++ classes are automatically translated to the Python or C++ convention, if they are originally specified using snake_case. All cross-references to C++ classes should therefore be specified as snake_case to be future-proof. This will also make it easier to eventually switch the Python section of the manual over to snake-case when we finished cleaning up the 1.10 docs and we feel like we're ready to branch off the 1.11 documentation.

Ah, that's fair. Hmm... Could you perhaps set a rule that replaces class-names in parameter/return data? That data should be fairly unlikely to include such collisions, and would be a rather useful place to have cross-links between classes, I feel.

Sphinx nowadays does this automatically, it seems, so this is done.

[ArsThaumaturgis]

All of those changes sound good to me, I believe! And thank you for all the work that you're putting into this!

And indeed, if #74 will make the process less tedious and troublesome, then I'm in favour of it, I believe!

[rdb]

Earlier I did another push with more links to the API reference and I will continue to add them when I find them.

Are there specific, actionable items you are still asking for in this issue other than "generally keep adding cross-references"? Otherwise, I am inclined to close it.

[ArsThaumaturgis]

Aside from what I described in the first post--which was rather general--I don't think that I have specific instances to point out. I do think that this can likely be closed, then!

Further, thank you for the cross-linking that you've done, and the statement of intention to continue to do so! ^_^