[Discussion] Class references using 1 page per function and add code examples about godot-docs HOT 8 CLOSED

Whatever the method of organization, the docs sorely need embedded examples.

2ndly, I think you're kinda throwing out the baby with the bathwater. . . the quest to find and use the best method to include examples has thus far resulted in no included examples.

I think so long as you minimize repetition, and use a portable/flexible/generic method (xml, json, etc) then there can be no wrong method, and any issues can be patched easily.

from godot-docs.

Ok, my 2c:

The script examples would be better if they are included via a BBCode tag (such as [script] Sprite_set_texture_001 [/script] or [script="Sprite_set_texture_001"]), since that would allow for much simpler parsing code (and reuse of the current code).

I guess the second method (with child pages) is much better for this, since we would get better organization with it.

from godot-docs.

@bojidar-bg You mention first and second methods as if they were two different proposals: they are not. What you so-call method 1 is actually what we currently have in godot-docs. Method 2 is the proposal :)

I didn't think about BBCode (even though I remember you mentioned it on IRC). I didn't use it because its syntax requires every opened tag to have a closing tag.

Thus, having only [script="Sprite_set_texture_001"] is erroneous since you miss the closing [/script]. In consequence, the only good solution here would be, as you proposed: [script]Sprite_set_texture_001[/script].

It would be indeed a good idea to use bbcode instead of XML <script id="..." />, so that we don't have to actually parse the content between <long_description></long_description>.

from godot-docs.

@StraToN your idea is aligned with how Processing is currently documenting their API.

Here is 1 page example: https://processing.org/reference/image_.html

It has Examples, Description, Syntax, Parameters, Returns and Related APIs

from godot-docs.

@BlenderNPR Yes, a little bit. The difference is that Godot functions are related to classes (so they're actually methods. In your example with Processing, image() seems to be a simple function.
Other that that, yes, the idea is very close.

from godot-docs.

Just throwing my idea out there because now it seems a bit difficult to achieve.

Since Godot 3 can export to HTML5, what if we include GDScript compiler directly in the docs? (kinda like W3School Tryit Editor or TutorialsPoint CodingGround)

Then every [script] or <script> tag can redirect to this editor. (For in-editor docs, maybe create new GDScript with script in the tag.)

from godot-docs.

the quest to find and use the best method to include examples has thus far resulted in no included examples.

Well, one could say that... but considering how much of the class reference was filled (or rather how it wasn't) I believe the problem is just the lack of documentation contributors. It's not that there are no examples, there's simply no documentation at all for a great part of the engine classes and methods. More truly so with the 3.0 changes (which just by being changed hinders the documentation effort).

I think we can still discuss a better way to include examples (and I'm a fan of a page per property/method), because 3.0 is just now getting stable enough to welcome documenters to do a job that won't be undone in a few weeks.

from godot-docs.

We've had some discussion, improvements to the parsing system, and now classref guidelines + more contributors, so let's see how it goes once the classref is > 80-90% complete, and we'll open new issues to discuss problems that'll show up then

from godot-docs.