Split general godot-cpp, general GDExtension info and GDExtension internals into separate categories.

[Ivorforce]

New Look:

Old Look: https://docs.godotengine.org/en/latest/tutorials/scripting/gdextension/index.html

The reason for this change is to entice more documentation to be made for godot-cpp (and GDExtension internals). The current structure does not clearly distinguish the two. By giving godot-cpp its own section, it can be extended meaningfully (in follow-up PRs) without cluttering the general GDExtension docs.

This was discussed in a GDExtension meeting, but the exact implementation is my own. I kept the changes as minimal as possible to make it unproblematic to merge. Still, I'd love to get some feedback, especially from other godot-cpp developers!

[Ivorforce]

I see there are absolute links from class_gdextension.rst and class_gdextensionmanager.rst to the exact godot-cpp example page. These will have to be adjusted.

Please let me know how best to proceed with this. Afaik, those files are generated from godot upstream, yes?

[tetrapod00]

FWIW, this PR is more or less the right solution in the abstract. However, we're running up against two problems with our docs: we need to avoid deep nesting of pages, and we also can't easily reorganize pages due to the limited number of redirects on RTD.

I have to express some skepticism at introducing extra nesting to pages in the scripting section of the docs. We recently merged some changes that reduce nesting, because the sidebar has a hard limit of 5 nested headers/page titles. At worst this can make whole pages unreachable from the sidebar, but even removing the ability to navigate to headers within a page is a UX regression I'd like to avoid if we can. Compare:

Before	After

I do see the advantage to having the pages about C++ and about GDExtension itself semantically separated, so if the GDExtension team thinks this is worth the disadvantage, it's okay with me. In that case, my suggestion would be:

• Merge the two new index pages into the existing index page, using sub-page headers to create nesting in the sidebar.
• Don't create any new folders to organize files yet. Keep all the pages and files at the same place in the directory structure, and only organize them in the RST table of contents. We use this approach in some other pages. This should avoid the need to change links from the class reference (a similar problem is holding up Move most of Scripting/Core Features section to new Core Features section #10384, FWIW).
• Possibly use the non-semantic fake header solution from Fix unreachable pages in sidebar by using fake headers in index pages #9989, so that the pages are organized within the single index page, but are not nested in the sidebar, to maintain the ability to click on headers within each page in the sidebar. But this does directly contradict the goal of reorganizing.

I made an alternate implementation of this PR with my suggestions: #10618.

[Ivorforce]

Thanks for looking into this! Avoiding more nesting is an interesting caveat indeed!

Your proposed solution is interesting too. If I'm understanding it correctly, it solves the 'sidebar' issue, but it would not solve issue on an articles level, correct?
Regarding this, i'm planning to expand the new C++ (godot-cpp) page quite a bit more in the future. Merging that into the parent index.rst would prevent this, if I'm understanding it correctly.

An alternative solution may be to pull GDExtension out of Scripting, or to pull C++ (godot-cpp) out of GDExtension. We briefly discussed this in the meeting as well. The verdict then was, this is worth considering, but we'd like to have a 'quick' solution first that can be quickly merged and iterated upon, without being very problematic. We hadn't foreseen nesting to be an actual problem 😅

[tetrapod00]

There are two problems here:

• We need a very good reason to move pages within the directory structure, since that breaks links and requires additional redirects which we don't have on ReadTheDocs at the moment. Of the two problems, this one is more of a hard constraint. My solution definitely solves that problem, since you can organize things in the Sphinx/RST structure in a way that doesn't exactly match the structure of directories.
• My solution doesn't solve the deeper sidebar nesting problem by default. But adding deeper nesting is kind of the point of this change, so if the GDExtension team considers that worth the downsides, I approve. We can avoid deeper nesting by using fake headers, but then the nesting doesn't appear in the sidebar.

I'm planning to expand the new C++ (godot-cpp) page quite a bit more in the future

If we go with my solution, then I would suggest making a new intro page for godot-cpp and putting under the toc-tutorials-godot-cpp toctree that exists in the main index page.

An alternative solution may be to pull GDExtension out of Scripting, or to pull C++ (godot-cpp) out of GDExtension

Pulling C++ out of GDExtension and making it a sibling of GDExtension and a child of Scripting makes a good bit of sense to me. But, semantically it also makes sense to keep C++ as a subcategory of GDExtension. I'm neutral here.
Pulling GDExtension out of Scripting doesn't make sense to me.

[Ivorforce]

Ok, I'm trying to understand the tradeoffs. I think this is the gist of it:

	Each sidebar entry is its own article	Links are kept intact	All articles keep 'table of contents' in navigation UI	C++ (godot-cpp) navigation depth
Move articles into other subfolders (this PR)	Yes	No	No	4 (Manual/Scripting/GDExtension)
Group articles with sections (#10618)	No	Yes	No	4 (Manual/Scripting/GDExtension)
Merge C++ (godot-cpp) up into Scripting	Yes	No	Yes	3 (Manual/Scripting)
Merge GDExtension out of Scripting	Yes	No	Yes	3 (Manual/GDExtension)

(Yes is good)

Technically all of those have similar amounts of downsides. All solutions are acceptable to me; all are better than the status quo, I think.
Personally, I'm leaning towards either of the last two options right now, because the 'table of contents' thing is probably worth keeping, and godot-cpp is 'important' enough to warrant being higher up in the navigation chain. But this is where I'd love to hear more voices!

[tetrapod00]

Summary looks accurate,

I'd also like to hear from other voices at this point, I'm mostly representing the maintenance of the doc organization.

[HuntJSparra]

(Speaking as a godot-cpp user)

Thanks for making the PR! All solutions looks like an improvement to me. I'm fine with whichever the crowd prefers, so feel free to disregard what I'm about to say:

Personally, I think that godot-cpp and GDExtension should be separated (option 3 in the table) because (1) "I want to use C++" and "I want to implement a language" are different user-goals that the docs mix up right now and (2) the godot-cpp documentation will get crowded if it grows in its current place. Maybe renaming the sections as "C++ via GDExtension" (as we refer to it on the Scripting languages page) and "Other Languages via GDExtension" would also help with this. It also makes a little more sense (to me) for the "Scripting" section since "GDExtension" is the only non-language in the list.

If that were done, there would be some overlap for the documentation system and .gdextension details, but I think the rest of it could be cleanly split. Though, I have only worked with GDExtension through godot-cpp, so I want to hear what the more serious users/contributors think, especially those who have made language bindings.

[dsnopek]

@Ivorforce thanks for making the PR!

@tetrapod00 thanks for the feedback!

For a tiny bit of background: this comes from a discussion at the last GDExtension team meeting, and the main motivation here is allowing us to write a whole lot more godot-cpp specific docs, without everything getting all mixed up.

I think if we do stick with having everything under "Scripting" -> "GDExtension", then PR #10618 is probably the better way to go, since it preserves the links. Having everything in one directory could be somewhat confusing for contributors, but that seems acceptable to me.

However, @Ivorforce's options 3 & 4 are interesting - restated by @HuntJSparra here:

Maybe renaming the sections as "C++ via GDExtension" (as we refer to it on the Scripting languages page) and "Other Languages via GDExtension" would also help with this.

So, then we'd have something like:

• Scripting
  • GDScript
  • C#/.NET
  • C++
  • Other languages via GDExtension

And we could make the "C++" section be godot-cpp specific.

Then the "Other languages via GDExtension" could list other language bindings, but we could also stick the GDExtension internals stuff under there too, with the idea that the internals are most interesting to folks who want to add a new language binding?

[Ivorforce]

It seems that the most popular option right now is to move godot-cpp up into Scripting. I tried this out in #10631.

This works really well in my opinion, and caters very naturally to the needs of docs readers, who will likely have the question "Which programming language do I want to use for my project?". Now more than before, this is my favorite approach.

[tetrapod00]

#10631 seems like a good solution overall, I'm in favor. Now it's more clear which languages are supported officially. The number of moved pages is minimal.

However, with the new structure, the first page in each section might need a more extensive rewrite. Repurposing the old What is GDExtension page to be about specifically C++ might change the original meanings in unintended ways.

[skyace65]

@Ivorforce since PR #10631 seems to be the preferred PR between these do you have any issues with this one being closed?

Also just a heads up, it might be a while until we merge the other one since the docs are at a redirection limit right now.