Godot: Add expandable code examples to the engine API docs.

[willnationsdev]

One common complaint is that the API docs tell us "what" an item (property/constant/method/signal) is, but not how it should be used. One simple way to fix that is to add a code sample that demonstrates it. While this can certainly be done in-place in the XML file, it seems more prudent to have somewhere else in the engine repository where this data is actually available, and then create macros in the API XML files that could generate spoiler sections with those code samples and descriptions in the in-editor docs and generated ReadTheDocs content. This would then make it easier for users to contribute examples that are consolidated in one place and then re-use those examples in all of the cases where those items are used.

By macros, I mean stuff similar to how [Vector2] results in a link to the Vector2 class's documentation, etc. You could similarly have a [sample <sample name>] or something.

Another extended option would be to implement a tagging system for each sample whereby users could specify which API items are used in a given sample and the engine automatically maps the samples to the items' docs, generating the spoiler sections without the use of a macro.

Is this idea too far-fetched? Do people think this would just be code bloat? If so, might we then go with an option that stores the code samples somewhere else (somewhere in the godot-docs repo maybe?) and then allow the editor to download the code samples so that they don't have to be bundled into the editor (though that would be less convenient).

WDYT?

[willnationsdev]

It seems like show/hide, i.e. spoiler sections, aren't something that Sphinx supports out-of-the-box, so if we did this, we'd have to add features (to the theme?) that allow it to do this in the generated .rst files...I think. I'm not a Sphinx expert (as you can tell).

[reduz]

The API doc xml has a tag where you can see links to documentation and demos using this function or class used. I filled a few of them but I think probably they need to be filled more/better.

[willnationsdev]

@reduz Wouldn't it be better if we could have the examples right there in the docs though? Having to navigate to a second location just to see an example is mentally exhausting on users, especially if they want to view samples for many different methods in quick succession.

I'd prefer it if reading the docs had an "everything is here" vibe. Though I definitely agree that having more links to relevant online documentation/tutorials is a good idea. Also, that's also kind of what #23395 is meant to help with in an automatic way.

[akien-mga]

Why have the code samples outside of the XML? If the samples are meant to illustrate a given class, they should be in that class file directly. I also don't want to add external Internet dependencies to this repository, it should be buildable without network.

[girng]

One simple way to fix that is to add a code sample that demonstrates it. While this can certainly be done in-place in the XML file, it seems more prudent to have somewhere else in the engine repository where this data is actually available

what do you mean "somewhere else"? take a look at the Directory page, it's great. has the example code that illustrates how to use get_next(). and is available on the online api page.

imo, docs like Directory are sufficient enough. has the code example there, and information for every method. if the code examples are added as spoilers for every method, browsing the docs might become too cumbersome. however, that's not really a bad thing.. i agree, more examples the better. but just playing devil's advocate.

[willnationsdev]

@akien-mga

I also don't want to add external Internet dependencies to this repository, it should be buildable without network.

I would prefer that as well.

Why have the code samples outside of the XML?

I would like to have separate XML content under the docs directory that specifically holds code samples and which we could then connect to individual items in the classes section of XML files. That way we can re-use code samples multiple times if they pertain to different items.

@girng

what do you mean "somewhere else"?

See above response to akien.

take a look at the Directory page, it's great. has the example code that illustrates how to use get_next(). and is available on the online api page.

And that is a terrific place to have a code sample appear for the object. But what if I created a more in-depth code sample that demonstrates, for example, how one might collect a list of all scripts in their project that extend a particular script file? This could demonstrate functions in Directory, File, Script, @GDScript, etc. This is a useful example to show someone because it is something that people might want to write in a real, production tool they create for the editor.

We could stash the example in a second location, connect to it, and, from that connection, generate an attachment to the relevant API doc items. That would make the creation of examples much more flexible and prompt the creation of more complex, but further useful code samples for people. As it stands, people often have trouble identifying how they should apply their API knowledge in real scenarios. That in turn makes learning Godot more difficult for them and results in a lot of complaints on forums that I've seen.

browsing the docs might become too cumbersome.

If we did this, I'd likely also suggest marrying it with an in-editor navigation sidebar for API docs pages to improve things. It's probably something we should do anyway. XD

[golddotasksquestions]

I have no clue about the technical implementation, but of course I would (as most beginners I assume) really appreciate more code samples illustrating the use.

[MysteryGM]

Expandable code examples, will be useful on expanding already complex documents like the shaders and signals; with examples.
I think they will be a create idea especially in the classes documentation.

Consider Godot's classes documents:
https://docs.godotengine.org/en/3.0/classes/class_collisionobject.html#class-collisionobject
VS Unity's documents:
https://docs.unity3d.com/ScriptReference/Collision.html ->
https://docs.unity3d.com/ScriptReference/Collision-collider.html

If clicking on the input_event() in Godot's documents showed a example of how it is used in a game, then it would improve use of the engine dramatically.
Of course important functions will have to be prioritized, because it is going to be no small thing to add examples to everything.

However if for some reason Expandable code examples could not be implemented, then links similar to Unity's could be a fallback.

[mnn]

Would love to this happening.

I personally like the idea of having source code outside and having it covered with automated tests, so when some changes in engine/API happen, you simply run all tests and instantly see which are failing and update relevant examples. This can keep docs (examples) in sync with changes in the engine, keeping user confusion to a minimum.

[Calinou]

I was thinking about how we could implement this in the editor help. We can define custom metadata and click actions in RichTextLabel, which would make it possible to add buttons to expand code samples. However, displaying the code sample (and folding it back) would likely involve regenerating the whole BBCode. This is a bit slow on large pages, but it should still be usable.

Multiple code samples will often be present on the same page, which means we'll need to keep other code samples folded when unfolding one of them (and vice versa). This sounds quite difficult to do.

[willnationsdev]

I was thinking about how we could implement this in the editor help. We can define custom metadata and click actions in RichTextLabel, which would make it possible to add buttons to expand code samples. However, displaying the code sample (and folding it back) would likely involve regenerating the whole BBCode. This is a bit slow on large pages, but it should still be usable.

Might it be simpler to just refactor the EditorHelp display so that it can have a VBoxContainer filled with potentially multiple Control nodes, not just a single RichTextLabel? Then you could have the spoiler buttons just be regular Buttons in between other RichTextLabel nodes. Or would that just be too many nodes generated in the display area?

Multiple code samples will often be present on the same page, which means we'll need to keep other code samples folded when unfolding one of them (and vice versa). This sounds quite difficult to do.

Isn't this the same logic that BaseButton and ButtonGroup have? Is there a reason we can't take a similar approach?

[justchen1369]

Another thing: perhaps add a warning about the sample code being possibly outdated when the automated checks fail?

[Calinou]

@justchen1369 We don't have automated code sample checks yet, and probably won't have for a long time due to how difficult it would be to add. If we were to implement it, we'd rather fix code samples than leave them outdated anyway :slightly_smiling_face:

[clayjohn]

Feature and improvement proposals for the Godot Engine are now being discussed and reviewed in a dedicated Godot Improvement Proposals (GIP) (godotengine/godot-proposals) issue tracker. The GIP tracker has a detailed issue template designed so that proposals include all the relevant information to start a productive discussion and help the community assess the validity of the proposal for the engine.

The main (godotengine/godot) tracker is now solely dedicated to bug reports and Pull Requests, enabling contributors to have a better focus on bug fixing work. Therefore, we are now closing all older feature proposals on the main issue tracker.

If you are interested in this feature proposal, please open a new proposal on the GIP tracker following the given issue template (after checking that it doesn't exist already). Be sure to reference this closed issue if it includes any relevant discussion (which you are also encouraged to summarize in the new proposal). Thanks in advance!