It seems people don't find current Class Reference documentation sufficient, and keep asking for "tutorials" for this feature or that function. While it is clear that for now, we need to clear the task of filling the classes.xml file, we can discuss the evolution of its presentation.

Other propositions available here: godotengine/godot#7360

Currently, each class is documented as one reference page. All members, functions and signals are listed and described in this page.
To enable documenters writing code snippets to show example(s) of usage for each function of each class, we need to have one page per function, accessible from the main class page.
Example for TODAY:

• class_sprite.rst
• every function is accessed in this same page, using anchor links.

Example FUTURE:

• class_sprite.rst
  • class_sprite_set_texture.rst
  • class_sprite_get_texture.rst

The idea is to have a similar organization as Unity documentation has:

• Main : http://docs.unity3d.com/ScriptReference/Graphics.html
  • Child : http://docs.unity3d.com/ScriptReference/Graphics.Blit.html

Having 1 page per function has the following advantages:

• allows documenters to document specific use cases, or add links to them if they are located elsewhere
• allows addition of code snippets

Disadvantages:

• since all the class reference is located in the classes.xml file, adding even more content in this file to create child pages for each class' function will inflate greatly its weight.

A potential solution to this problem would be to split classes.xml into 2 XML files; the second one would contain long descriptions in it, but I feel it will be somehow problematic for maintenance.

I recommend to keep classes.xml's current structure and the current "short" description we have for each function, as we need them to be displayed in the main class page. In the main page, each function name should now be a link to the corresponding child page, which is filled with the content of another tag in classes.xml.

classes.xml methods current structure:

<method name="set_texture">
    <argument index="0" name="texture" type="Texture">
    </argument>
    <description>
    Set the base texture for the sprite.
    </description>
</method>

New structure:

<method name="set_texture">
    <argument index="0" name="texture" type="Texture">
    </argument>
    <description>
    Set the base texture for the sprite.
    </description>
    <long_description>
    *Here is the content of the child page.*
    </long_description>
</method>

Code examples:
We must not forget future translations for class reference. We have no choice but to duplicate (in the future) classes.xml file for each language (classes.en_EN.xml, classes.fr_FR.xml, etc).
However, certain portions of long descriptions of each class method could be shared by every translation : scripts and source codes.

In that way, script examples could be inserted in another XML file (classes.script_examples.xml). Each script can be identified with an ID (designed to be unique, say <classname>_<function>_<XY>) and called from classes.xml using a special tag, like: <script id="Sprite_set_texture_001" />.

Here you go.
Discuss !

Moving godotengine/godot#73 here.

Cloning from godotengine/godot#988

Hi, the section says the dot product is hard to understand and makes no sense.
But I’ve found a really nice and intuitive way to think about it:

The dot product simply is the indicator for how much two vectors have in common.
The bigger, in relation to their magnitudes, the more two vectors have in common.
Simple. :)

I think that it’s hard / makes no sense is a false meme,
and it’s just the explanation we learned it from that has always been bad,
which instilled fear, and caused us to have trouble understanding it in the first place.

So I hope you can add the above explanation,
and remove the lines about it being hard or making no sense. :)

The issue in godotengine/godot#5108 was closed because it is possible already, but the remote debug option is not very well documented.

A tutorial showing debugging inter PCs would be interesting.

guide how to achieve common tasks (eg: how to make character customizabe. how to make camera follow ball. how to use two cameras/viewports for left and right eye (or see zoomed thru a scope of a gun).

In the " Instancing (continued)" tutorial are should be changed to as in the following piece of text:
"Make some rooms with furniture, then connect them. Make a house later, and use those rooms are the interior."
I could be wrong but I am pretty sure that are should be as.

See http://docs.godotengine.org/en/latest/tutorials/asset_pipeline/exporting_projects.html#export-dialog

A user on Facebook assumed that the end of this section meant that he had to look for the export templates on the wiki.

I guess some people are really waiting to learn about this topic (I know I do).

Can we expect a tutorial for it anytime soon?

BTW: Thank you for amazing work on the engine and the documentation! You are amazing!

In order to ease documentation translators' work, we intend to build a script/webapp showing concrete differences between English files versions between commits in time.

For following explanations, French (FR) example is taken. It will of course be valid for ALL translations.
English (EN) translation is supposed to be the basis of ALL translations.

Here are all the requisites:

• Sort commits from EN and FR chronologically
• Display them on a timeline : http://pasteboard.co/1CKx8ZKH.png
• Show a diff tool displaying the differences between the previous EN commit which happened before last FR commit, and the latest EN commit. That way, FR translator can impact all changes that happened between the last EN commit which was already impacted to FR, and the latest (most recent) EN commit, even if there were 100+ EN commits in-between.
• In the image example: hoi2djn is the last EN commit that was impacted in FR (dq22a21). However, the latest EN commit is 12315aq, which is not impacted in FR yet.
• Each commit hash would be a link to the commit on GH
• Files that do not exist between EN and FR should be notified (eg: French user-made tutorials not existing in English, and the inverse)

We think this application should be accessible from a web page.

I think that Physics introduction is a bit messy. I have not a good structure because I need to understand the usage and meaning of each node, but someone with better knowledge could reorganize it.

when attempting to get into Godot via

http://docs.godotengine.org/en/latest/tutorials/step_by_step/scenes_and_nodes.html

i quickly noticed the screenshots are outdated, this causes a couple problems. first being that if the screenshots are outdated, my confidence in the fact the text itself is up-to-date and will allow me to learn the software without a hitch is not very high.

and two, arguably the most important for me is the fact that the lack of up-to-date screenshots can cause a problem for a good albiet small percentage of users, i myself, like others that exist use visual references to help learn.. and out-of-date screenshots will make that a bit more difficult. not impossible, but just a bit harder

Searching at docs.godotengine.org for 'OS' returns 0 results.
I think it should return at least http://docs.godotengine.org/en/latest/classes/class_os.html

I remember @punto- mentioning that Godot supports using multiple PCK files to handle game extensions, DLCs, user-made content, etc.
This is however not documented as far as I know, so it's something we should write about (hopefully with some pointers from @punto-).

The tutorial GDScript more efficiently strikes me as misleadingly named. The title (and introduction) suggests that it's a guide to optimizing GDScript code (which would be interesting and give more insight into the language's underpinnings). But apart from some examples of GDScript usage that seems to have little to do with efficient use, there is no real discussion of performance from the perspective of a GDScript user. Rather, this tutorial is squarely aimed at exemplifying GDScript code to developers coming from statically typed languages like C or Java.

So I suggest renaming this tutorial to something more informative like "GDScript compared to static languages".

It took me a while to realize that I needed to perform a "chmod +x" on the downloaded file in order to get the Godot Engine to run on my Linux machine. I'm not accustomed to ".64" files, nor have I ever encountered one prior to this application.

I think creating an "Installation" section in the documentation would be useful for all future users of the engine.

Clone from godotengine/godot#1258 by @leiserfg:

Can someone write in the wiki how to use this singleton on android? I saw that in the java source but I'can make it work from gdscript.

As commented in IRC, categories need a revision, so we can publish suggestions in this issue.

from IRC:

djrm_   so current categories, TUTORIALS, REFERENCE, COMMUNTY ?
StraToN currently yes
I tell you what I think: I'd add 2D, 3D, Sound, Netword, Physics
Network*
djrm_   as core categories?
StraToN yep
These are ideas only, right? Nothing decided yet
djrm_   so inside every one there would be like tutorials and stuff like that
so 3D -> [tutorials, cheat sheets, reference]
StraToN djrm_ For reference it's problematic, we can't separate
djrm_   yeah, as top categories i would put: LEARN, REFERENCE, CONTRIBUTE
StraToN ah, interesting, I like this LEARNING category
what do you put inside?
djrm_   LEARN -> [ getting started, how to's,]
tutorials
guides
for example asset pipeline would be a how to
also editor plugins
and math would be in guides
Mesh generation with heightmap and shaders could be in how to also
Engine section should be in getting started
i mean could
maybe REFERENCE -> MANUAL, making emphasis that is somehing more technical

Please correct me if I'm getting it wrong, but it looks to me as if the example code in the tutorial ( http://docs.godotengine.org/en/latest/tutorials/engine/saving_games.html ) results in an incresing number of nodes every time a game is loaded.
Moving "var currentline = {}" inside the while loop worked in my test project, but I don't know if that is a general fix.

There's quite a few keyboard shortcuts in the editor but I miss a list of all of those. Not sure how to organize those, since many are context-dependent. I guess a single page with different context sections should be enough.

When going through the tutorials there should be links for further reading.
At least a link to awesome godot (which is a great resource), would be a nice hint for every beginner.

Some users reported on the Steam forum that the Pong tutorial is a bit hard to follow for newcomers: http://steamcommunity.com/app/404790/discussions/0/364040166684451403

Several issues:

• the code diverged a bit from the pong demo (likely the demo is better)
• there is no clear overview of how the things should be positioned or how the script should look like

Need documentation to explain how to add compile options for the custom module only so they don't affect the whole engine. As discussed in godotengine/godot#4490.

Cloning from godotengine/godot#896

Raycasting and matrix operations are very interesting features,
but require some love in documentation area. It is very hard to find odds/ends for
someone without game engine experience (but with average math knowledge) like myself.

See http://steamcommunity.com/app/404790/discussions/0/364042703865087202/

We have the "Batch building templates" page but it's not really user-friendly. We should maybe add a section about building and packaging the templates on the Compiling for {X11,Windows,OSX} pages.

I don't get how to translate files.

To translate an existing page, simply copy its original content. Then, create the new page in the section of your language, copy the English content in it and start translating.

Where to find/place the sections?
Sorry if I overlooked something.

Moved from godotengine/godot#4525

Notably, list the BBCode tags that are supported in the classes.xml, like [code] and [codeblock].

Assets Pipeline currently contains following sub-sections and pages:

• General
  • Managing image files
• Import
  • Import process
  • Import textures
  • Import fonts
  • Import audio samples
  • Import translations
• Export
  • Exporting projects
  • One-click deploy
  • Exporting for PC
  • Exporting for Android
  • Exporting for iOS

As we can see, the "Export" section does not rely to assets, but projects export. I propose that this "Export" section moves elsewhere (or becomes a new section), and to rename "Assets Pipeline" to "Import Assets", or "Managing Assets"

a section to tell which formats are scm friendly when we have multiple choices.

The instruction on http://docs.godotengine.org/en/latest/tutorials/ssl_certificates.html is outdated. I can find nowhere in the project settings letting me configure the certs. And I'm not quite clear what does the "Filters for non-resource files" part do.

Much appreciate any help on updating the doc and adding some explanation.

Thanks!

See:
http://docs.godotengine.org/en/latest/reference/gdscript.html#comments

Now place:
""" Everything on these
lines is considered
a comment """

It delivers the following error:
Unexpected token. Constant:

When I access https://docs.godotengine.org, Firefox prompted me the following error:

docs.godotengine.org uses an invalid security certificate.
The certificate is only valid for the following names: *.readthedocs.org, readthedocs.org
Error code: SSL_ERROR_BAD_CERT_DOMAIN

I saw somewhere that this wasn't possible because it's bitmap or something like this. But in Unity, for example, you can resize your text from the text component itself, and don't need to import a new font size each time.
Maybe if you could adjust it in the label node (or other node that displays text) and then it create the .fnt when compiling. That way you could prototype quickly and it would just import it when necessary (when you actually run the game).

Since there is a huge inflow of new/potential users right now, it would be nice to have a guide for transitioning them from Unity's way of thinking to the Godot way of thinking.

Adapted from IRC (meeting on -devel, 2-nd of June):
[reduz] as you and many probably noticed, the change of license in Unity generated a lot of people angry and an unexpected large amount of new Godot users and discussions of Godot as an alternative in many places
[reduz] I´ve seen two things used as argument from people that would like to switch, one is of course support for C#, which I guess we´ll have to eventually implement. The second is documentation or tutorials on how to move workflow from Unity to Godot. Some sort of ¨map¨ of how something you do in Unity is done in Godot
[reduz] do you think we could assemble some sort of mini team to work on this kind of documentation? I know Unreal has a large article about this for Unity users, but anything that could ease their transition, specially for advanced users, while at the same time being able to show how we do many of the same things in Godot better would be fantastic

Original issue by @mrbw85 on godotengine/godot#4730

func wrap(value, minVal, maxVal):
        return (((value - minVal) % (maxVal - minVal)) + minVal)

does not want to take the float that delta represents in:

func _process(delta):
        angleFrom += rotAngle * delta
        angleTo += rotAngle * delta
        angleFrom = wrap(angleFrom, 0, 360)
        angleTo = wrap(angleTo, 0, 360)
        update()

gives error: Invalid operands 'float' and 'int' in operator '%'.
what syntax does

func wrap(value, minVal, maxVal):
        return (((value - minVal) % (maxVal - minVal)) + minVal)

need to be in order to accept delta value?

say android accelerometer, camera, swipes gestures etc..

From godotengine/godot#4419

Collision Layers & Masks are not even mentioned in Godot Docs. Any many people ask about them or ask about problem, which could be solved with those.

examples from today, from Godot's FB group:
https://www.facebook.com/groups/godotengine/permalink/765588073577789/
https://www.facebook.com/groups/godotengine/permalink/765659656903964/

I was told about this feature on IRC, when I had similar problem to those guys. And only description of those layers/mask I've found is here:
http://godotengine.org/qa/3020/collision-masks-and-its-propper-uses

Briefly mentioned on QA.

Currently the BBCode language reference doesn't even contain information about the list of supported tags, a basic syntax example (we can't assume everyone has been using a BBCode-enabled forum all his life, right?), and probably a few helpful tips, if needed.

What

The img-folder looks like a cluttered depot of unsorted images.
What about a simple folder structure (like creating a folder for each doc-page) or naming convention (docpage_ham_and_eggs.png)?

Pro

• If an image is outdated, it can be found and replaced very fast (without the need to search the images title at first)
• If a page is deleted the corresponding folder can be deleted as well (no gathering all included images)
• If someone wants to add an image with an existing name (which seems to be not that unlikely) it has to be renamed at first to not override another (just annoying)

Con

I know this would take much editing (every file, that uses images plus the renaming/resorting of images itself) and has no huge effect. But it could be done step by step and would be an improvement in the long run.

@brettle had made a patch against the GH wiki (in Markdown) but it was sadly never merged.

Now the docs are in reST so the patch obviously can't be applied, and many of those fixes have probably already been done, but it would be great if someone could check them and see if some are still relevant:
https://gist.github.com/brettle/10007085

(raw patch: https://gist.githubusercontent.com/brettle/10007085/raw/6a4f14d57d34af504a2e0bc4e037a91974c03000/godot.wiki-readability.patch)

(Moved from godotengine/godot#256)

The preparation task of documenting Godot demos (available here: https://downloads.tuxfamily.org/godotengine/2.0.2/Godot_v2.0.2_stable_demos.zip) has started with the creation of the demos/ folder in the present repo (https://github.com/godotengine/godot-docs/tree/master/demos).

Even though each demo has an empty page already created, we feel that some demos may get out of the "official" list and some may be replaced by new ones. This topic discusses this question.

First things first, I propose to sort current demos in 3 lists:

• Keep and/or improve : these demos will be documented first.
• Replace by a better one : we will need to develop new demos
• Remove

Please help us filling these in this Etherpad: https://v.etherpad.org/p/godot-demos-docs

Then, we will track a new list with whole new demos that you may feel currently missing. Remember each demo will then have its own documentation page. You can propose your ideas in the according section of the previous Etherpad.

Thanks !

See:
http://docs.godotengine.org/en/latest/reference/gdscript.html#keywords

There is no where in the documentation where it mentioned the proper use of export encryption keys. A lot of people would want to know how to do this to protect the game from cheaters, hackers, and profit etc.

Since godotengine/godot#4905 there's a new dependency for xrandr, so it should be added the documentation. It's called libxrandr-dev in Ubuntu and libxrandr in Arch, but I don't know about the other distros.

Need documentation to explain how to use (read) new "Profiler".

I've been thinking about updating some material for the docs in order to match the new features in 2.1, but it came to my mind that it is possible that some people for some particular reason want to stay in an older version of godot, so maybe the documentation should have something like different versions.
Of course this introduces the big problem of the fragmentation of the documentation, since basically more content will be added for newer version, while the previous versions get outdated. (notice that this fragmentation is natural and inevitable since there's already a lot of unofficial content targeted to the current version)

I would prefer to keep the official documentation up to date with the latest stable version.

In the "GUI skinning" section, under "creating a theme" it should show a relevant UI image for creating a theme, but instead repeats the previous image.