Split C++ (godot-cpp) and GDExtension system info into separate categories, children of Scripting.

[Ivorforce]

This is an alternative to #10617.

Please don't discuss this PR here, discuss the options in #10617 instead (apart from change reviews).

This PR specifically rearranges articles such that Scripting now has these children:

C++ (godot-cpp) and The GDExtension System are split off from one another because they cater to different target groups (godot-cpp for C++ users, GDExtension to language bindings implementers).
Other Languages is taken from the previous GDExtension article, and is targeted at people that want to code in other languages.

I kept the changes as minimal as possible, but rearranged some articles and added intros to make it flow better with the new structure.

[tetrapod00]

To deal with the build errors:

/home/runner/work/godot-docs/godot-docs/about/docs_changelog.rst:348: WARNING: undefined label: 'doc_what_is_gdextension' [ref.ref]
/home/runner/work/godot-docs/godot-docs/about/faq.rst:193: WARNING: undefined label: 'doc_what_is_gdextension' [ref.ref]
...
/home/runner/work/godot-docs/godot-docs/classes/class_gdextension.rst:31: WARNING: unknown document: '../tutorials/scripting/gdextension/what_is_gdextension' [ref.doc]
/home/runner/work/godot-docs/godot-docs/classes/class_gdextension.rst:33: WARNING: unknown document: '../tutorials/scripting/gdextension/gdextension_cpp_example' [ref.doc]
/home/runner/work/godot-docs/godot-docs/classes/class_gdextensionmanager.rst:31: WARNING: unknown document: '../tutorials/scripting/gdextension/what_is_gdextension' [ref.doc]
/home/runner/work/godot-docs/godot-docs/classes/class_gdextensionmanager.rst:33: WARNING: unknown document: '../tutorials/scripting/gdextension/gdextension_cpp_example' [ref.doc]

This anchor _doc_what_is_gdextension is referenced from three places:

• https://docs.godotengine.org/en/latest/about/faq.html#which-programming-language-is-fastest
• https://docs.godotengine.org/en/latest/tutorials/scripting/gdextension/what_is_gdextension.html#doc-what-is-gdextension
• https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_web.html#thread-and-extension-support

And it's referenced as a URL from a few places in the class reference.

I would recommend:

• Remaking a page tutorials/scripting/gdextension/what_is_gdextension.rst
• Add what_is_gdextension back to the gdextension/index.rst table of contents
• Give the new page these contents:

.. _doc_what_is_gdextension:

What is GDExtension?
====================

Placeholder.

That should resolve the CI errors for now while we figure out exactly how some of the content gets shuffled around or rewritten. It's possible that we want to keep that What is GDExtension page in some form.

To be clear I recommend fixing the CI issue now but you don't need to start working on the overall rewrite (if needed) until GDExtension maintainers comment

[tetrapod00]

This section may now be out of place, it talks about GDExtension overall rather than godot-cpp specifically.

[Ivorforce]

This section is important to people who'd consider using godot-cpp: They need to know how compatible their extension will be across versions. It needs to be discussed here, or at least linked to another place where it is discussed.

It is as important to people who'd consider making their own GDExtension from scratch, so it might be warranted documenting it there too. But I'd argue that these people are more familiar with GDExtension anyway and don't need to be told this again explicitly.

[tetrapod00]

It's possible we want to fold this page into the The GDExtension system page, maybe called Other languages with GDExtension. But I do see the appeal of listing "other languages" explicitly in the table of contents.

If we keep it, we don't actually use Title Case for titles in the sidebar:

Suggested change

	Other Languages
	Other languages

[Ivorforce]

I think it's more important for people to find this place out of the use-case of "What language can I use with Godot?" rather than "What bindings exist using GDExtension?", for the same reason we're moving C++ (godot-cpp) out of GDextension in the first place.

(will adjust the title case)

[Ivorforce]

I made quite a few changes. Hopefully the CI issues are resolved / better now. But changes are accumulating :D

• I have added back an empty "What is GDExtension" document.
• I have moved C++ info to an About godot-cpp article, as opposed to the top article.
• I have renamed the godot-cpp example page to Getting Started, and added a top section giving a short introduction.
  • I expect some of this info can be moved into detail pages some other time.

Here's the current status (parts at least):

Looks a lot better still, in my opinion!

[dsnopek]

Thanks, this is looking really good to me!

I have just a couple notes on some of the new text.

[tetrapod00]

Looks good. I didn't reply to all your replies individually, you made a lot of good points and I trust your overall judgement here, I was mostly calling out things that may need changes. I left some of the conversations unresolved so other reviewers can see them.

There are a couple more docs syntax/conventions things to address, plus the question of what to do about What is GDExtension and the links from the class reference.

[tetrapod00]

One more thing: do we want to keep some form of a What is GDExtension page?

I initially suggested it cause it was the cleanest way to resolve the CI errors.

If we decide to remove:

• I believe we need a PR for the class reference to change the links:
  • https://github.com/godotengine/godot/blob/3f56b3b23916ff54a1715cb8444304ce3c50283d/doc/classes/GDExtension.xml#L11-L12
  • https://github.com/godotengine/godot/blob/3f56b3b23916ff54a1715cb8444304ce3c50283d/doc/classes/GDExtensionManager.xml#L11-L12
• If we're doing that, we need to find a new link for the general GDExtension link.
• And we might as well properly rename the getting_started.rst page if we're already making engine PRs that are changing URLs.

If we decide to keep it, then we need some content, and I'm not sure what.

[Ivorforce]

It definitely makes sense to me to have some page explaining GDExtensions in concept! I would have initially put it into the GDExtension nav page, but since this does not seem to be the way of this wiki, I'm happy to have a separate page for it.

I think I may be able to magic up some contents for it for this PR too, without being too lengthy or controversial. The rest can be added at a later date, then.

[tetrapod00]

A good tool here might be the new What is GDExtension page linking to the About godot-cpp page which used to be the What is GDExtension page. In the absolute worst case we could leave it as a short stub page as a "redirect", we do this in a few other places in the docs already.

[Ivorforce]

Alright, I've written a bit of boilerplate / some initial useful info. Can definitely be expanded, but it's not empty. Let me know if you think it needs more info!

[Ivorforce]

@tetrapod00 I think I've addressed all the discussions that have been put up so far. CI is still failing (even after renaming the files back to what they were) because they're found under different paths now. I suppose I could move them back to the gdextension folder without breaking the nav we have right now, but that might be confusing for contributors.
Perhaps it would be possible instead to touch the class docs temporarily, and make a PR to Godot upstream to change class docs permanently there too?

[tetrapod00]

Oh, I missed that gdextension_cpp_example.rst moved folders too, sorry for the bad advice. In this case I think it would be appropriate to temporarily change the link in the class reference file so the CI passes and we can check that everything else is okay. Then we can do an engine PR to change it permanently.

To be honest I'm not actually sure exactly what the right protocol is when we need to move a page that is linked from the class reference, so would need a class reference change. CC @mhilbrunner?

[tetrapod00]

I built locally (after fixing errors by temporarily changing the links in class_gdextension and class_gdextensionmanager to point to ../tutorials/scripting/godot_cpp/gdextension_cpp_example rather than ../tutorials/scripting/gdextension/gdextension_cpp_example. It compiles and looks fine from a docs organization point of view.

I think the new short What is GDExtension page is good, serves the role of a landing page for the old link, and can be expanded in the future if needed. Needs a GDExtension team review.

This looks good overall. What's left from my point of view:

• We still need to resolve the other link redirect for gdextension_cpp_example, somehow. Needs a second opinion from someone else on the docs team.
• The new short What is GDExtension page needs a GDExtension review.
• I only noticed this now, but we may want to rename the folder (but not the visible category name) for godot-cpp from godot_cpp to just cpp, to match the convention for GDScript and C#, and possibly be a bit more future proof.

Great work, thanks for being so responsive to reviews. I wish that moving pages was as simple as your first proposed PR. This process also exposed some places where we should probably document how Sphinx and RST work a little better, along with the process for moving and renaming pages.

[Ivorforce]

Great work, thanks for being so responsive to reviews.

I can only return that, you've been incredibly helpful in pushing this change along. Thank you! ☺️

I only noticed this now, but we may want to rename the folder (but not the visible category name) for godot-cpp from godot_cpp to just cpp, to match the convention for GDScript and C#, and possibly be a bit more future proof.

Good idea, will do!