Add code examples in a separate directory

[anarchy-chan]

As discussed in #128, here is a rough draft for an examples directory.

There are still a few design decisions that have to be taken care of.

• How do we deal with duplicate information? I think it makes sense to mention runtime Variant type checking in the Array example, but it also makes sense to mention it elsewhere.
• How do we want to split the documentation? Is something like arrays.lua fine or do we want it to be inside a bigger variants.lua file? The latter would be fine, as long as we mention that this file contains information about arrays (for people specifically looking for that).
• Is a flat structure fine or do we want a more nested one? We could also do a mixture of both by having more general things in the top level of the examples directory, but also directories for more specific things, like full project examples.
• Should the examples be run as tests?

It's still far from what I'd like it to be, but what do you think @gilzoide?

[gilzoide]

Hey @anarchy-chan, thanks for working on this.

Overall, I think we could have the examples live inside a single Godot project, which could be the same as the one currently being used for the automated tests (we could rename it from "test" to "example_project" or "examples" or something like that). This way they could be editable / runnable when opening such project with Godot editor.

We could even have a scene for opening / editing / running these Lua script examples to make it even more interactive. We can then export this project to web and host it using GitHub Pages for people to try out.

What do you think?

How do we deal with duplicate information? I think it makes sense to mention runtime Variant type checking in the Array example, but it also makes sense to mention it elsewhere.

It's fine having duplicate information if such information is relevant in both places.

How do we want to split the documentation? Is something like arrays.lua fine or do we want it to be inside a bigger variants.lua file? The latter would be fine, as long as we mention that this file contains information about arrays (for people specifically looking for that).

I think a "variants" or "builtin_types" or "builtin_variants" folder with one example file for each Variant type (except for trivial ones like nil, bool, int and float) would be a nice middle ground. Adding an example file for Strings could be nice as well, since when opening the GODOT_VARIANT library we can call Godot String methods in Lua's strings in addition to the usual ones from Lua.

Is a flat structure fine or do we want a more nested one? We could also do a mixture of both by having more general things in the top level of the examples directory, but also directories for more specific things, like full project examples.

As mentioned above, I'd say one extra level of directories is fine to group examples in a similar category if it makes sense. For built-in Variant types I think it would make sense. Maybe another folder for LuaScript examples. As for full project examples, I think it's simpler to have everything in a single Godot project instead of creating multiple projects in separate folders. This way people can explore everything by opening a single project in Godot.

Should the examples be run as tests?

It wouldn't hurt, we could run them just to be sure they won't error when people open them in Godot. It's useful to run these things also to make sure examples work in both Lua 5.4 and LuaJIT variants of the addon.

[anarchy-chan]

Overall, I think we could have the examples live inside a single Godot project, which could be the same as the one currently being used for the automated tests (we could rename it from "test" to "example_project" or "examples" or something like that). This way they could be editable / runnable when opening such project with Godot editor.

We could even have a scene for opening / editing / running these Lua script examples to make it even more interactive. We can then export this project to web and host it using GitHub Pages for people to try out.

What do you think?

This sounds good, as long as we also keep the example scripts as well. The interactive project would be better for first time users, while example scripts are easier to reference if you know what you are looking for.

It's fine having duplicate information if such information is relevant in both places.

Alright, I agree. The only issue with that is that all places where the information is duplicated have to be kept up to date if anything changes. We could generate the documentation in some way, but that would make things more complicated.

I think a "variants" or "builtin_types" or "builtin_variants" folder with one example file for each Variant type (except for trivial ones like nil, bool, int and float) would be a nice middle ground. Adding an example file for Strings could be nice as well, since when opening the GODOT_VARIANT library we can call Godot String methods in Lua's strings in addition to the usual ones from Lua.

Yeah, that would be better. That way we hopefully wouldn't need any duplication to begin with. But I don't particularly like the three names you suggested because they aren't very intiuitive for new users who haven't used GDScript before. But the meaning could be explained in a readme referencing the directory. Nevertheless, I'd veto for a name like collections or something else that is common in other programming languages and then explain that it refers to Godot Variant types, like Strings, Arrays and Dictionaries.

As mentioned above, I'd say one extra level of directories is fine to group examples in a similar category if it makes sense. For built-in Variant types I think it would make sense. Maybe another folder for LuaScript examples. As for full project examples, I think it's simpler to have everything in a single Godot project instead of creating multiple projects in separate folders. This way people can explore everything by opening a single project in Godot.

I'd either put that into examples/project, examples/godot_project or example_project (in the root dir).

I'll have more time to work on this toward the end of next week, but until then I'll most likely be too busy.