Organise classes into different divisions of the engine.

[Splizard]

A complete and total set of divisions have been designed to enable
better class discoverability by offering an alternative path for class
exploration where each division exists as a curated "Class Reference"
for the specific area of functionality it covers.

They also serve as an officially maintained set of divisions to be
consumed by thirdparty Godot bindings so that classes can be organised
into sensible groups, rather than a single global namespace (which can
be an intimidating amount of symbols for a single
reference/module/package/namespace/library).

I decided to have divisions defined in their own folder (rather than
inside the per-class xml files) so that they can/will be maintained
holistically. It may be worth adding a few scripts to support this, ie:

* Detect missing classes.
* Remove deleted classes.
* Rename updated classes.

The "Class Reference" sections have been embedded directly into the
respective index files (would it be better suited to have them as their
own pages?).

Started by splitting the divisions based on the functional teams:
https://godotengine.org/teams

I made some design calls around splitting core into engine, multicore
and math & followed up by integrating this with the tutorial sections
which are already nicely split across functional boundaries.

Core text functionality has been grouped together with translation.
Conceptually this works for me but the tutorial would need to be updated
to match (for this to make sense).

Also note that I've awkwardly placed the 'engine' division "Class
Reference" under the "Best Practices" page (I noticed that there doesn't
appear to be a general engine section/overview). I didn't want to orphan
it but perhaps a new 'engine/mainloop/scenetree' section could be added.

This is an implementation of #6137 and godotengine/godot-proposals#4543.
I chose not to make any changes to to godotengine/godot as I consider
the solution here to be primarily developer-experience &
documentation-focused and not a concern for any of the functional teams.
Even if class tags become a thing in Godot 5, I think having divisions
defined here will still be valuable.

[YuriSizov]

This is an implementation of #6137 and godotengine/godot-proposals#4543.
I chose not to make any changes to to godotengine/godot as I consider
the solution here to be primarily developer-experience &
documentation-focused and not a concern for any of the functional teams.
Even if class tags become a thing in Godot 5, I think having namespaces
defined here will still be valuable.

Well, no. Such changes should be available in the built-in documentation as well. Besides, having it hardcoded like that here makes it very hard to maintain. This should really be a responsibility of each class, as defined in the engine source, not be implemented as a hack on the web documentation side.

We also don't want to have the classes namespaced, we want them tagged/labeled. Because some classes would belong to several areas, thus making namespacing impossible without sacrificing discoverability in favor of one of the areas. Which is why the agreed upon solution is to have grouping, in engine, with multiple possible groups assigned to the same class.

[Splizard]

Well, no. Such changes should be available in the built-in documentation as well. Besides, having it hardcoded like that here makes it very hard to maintain. This should really be a responsibility of each class, as defined in the engine source, not be implemented as a hack on the web documentation side.

I stand by my PR and I don't consider it a hack nor do I think that it would be very difficult to maintain, with a couple of scripts to check for missing classes and/or removed classes, a single API designer can intermittently keep things up to date. I don't see how a class can effectively determine it's own organisation, as this would more effectively be derived by the pattern and context of its use (ie. array elements do not reference the array they are embedded in).

https://docs.godotengine.org/en/stable/index.html is one of the most important places for Godot users to build up a representation of the engine and its associated set of features. Yes, it could be useful to have these divisions documented within the editor. It could also be useful to have the tutorials embedded directly in the editor. I don't see any reason why this couldn't happen in the future.

We also don't want to have the classes namespaced, we want them tagged/labeled. Because some classes would belong to several areas, thus making namespacing impossible without sacrificing discoverability in favor of one of the areas. Which is why the agreed upon solution is to have grouping, in engine, with multiple possible groups assigned to the same class.

The issue is that class-defined tags do not appear likely to address the user stories presented in either of the referenced proposals and it's not clear how they will be valuable to users, perhaps they'd make searching through the offline builtin documentation a little more convenient. Having arbitary tags won't encourage a shared language and understanding of the engine, so they'll need to be curated and discussed by the creator of the class, this will delay PRs and get in the way of exposing new functionality. Third-party bindings will lack a design direction. As things change in the engine, there will be a desire to change and reorganise how the Godot APIs are presented. This will be very challenging to manipulate if/when all the tags and areas are defined in each class.

There's no reason why a future design couldn't have AnimatableBody2D in both physics and animation. It's up to the designer(s) to make these decisions. There is a large number of engine components (classes) and dividing them up holistically, officially and deliberately is a valuable way to help users build a model of the engine's capabilities.

[YuriSizov]

I'm sorry, let me explain why I called it hacky. The problem with your solution is that you are not changing the source of this data. If the changes are made to the source, it then remains the single source of the information, which multiple users can potentially access. For example, categories can be used to generate namespaces for alternative language bindings, such as C#, Rust, etc. It's not just about having the docs in the editor in parity with the online documentation, though that is important too.

And you solution instead only changes one view, one representation of that information. It is harder to maintain. The source is maintained by multiple teams of multiple people, responsible for their own areas of the engine. Godot is a collaborative effort and its strongest aspect is the team of contributors that come and make sure the engine functions well, and is organized well. While there are some people who do the overarching maintenance, their plate is full as is, and their job is mostly to enable other maintainers, not to be the bottleneck that must be passed for things to be released.

So your idea that we could replace all that with some person who's going to be responsible for the upkeep of the online docs just so we can have categories is going the wrong way from what our organization is. We don't have a single API designer, nor do we plan to make someone personally responsible for that. Nor does it make a good plan to have extra scripts to double-check if the information here is up to date. Most of our checks are automated, and the docs are automatically generated. It already takes a person to sync the main repo with the docs, and there is no point adding to their list of tasks, either manual or semi-automated. Each such task is another pain and another point of potential failure.

So with all that, yes, we want to have a system that is self-contained and self-organized, with nodes themselves, or at least some shared code in them declaring which category they belong to. It only makes sense, because the people who author that code know the best about which categories to use. And it keeps things in one place, under the collective watchful eye. And it lets third-party tools to utilize that information, just like they can utilize everything else from the ClassDB data.

[mhilbrunner]

Thanks for taking the time to contribute to Godot's docs. We can always use more hands. :)

Due to the reasons outlined above, this isn't the best way to solve this. If in the future you want to avoid doing duplicate work, it can help to discuss feature PRs beforehand, especially for proposals where the (path to) implementation isn't yet agreed on.

For the docs specifically, we tend to hang out in the #documentation channel on the official Godot Rocketchat.

Sorry we can't merge this one, but again, thanks for taking the time to contribute to Godot!