From 1b0aff29aa167bbe342f096303b7d125d2eeb12d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Verschelde?= Date: Fri, 19 Feb 2016 20:15:14 +0100 Subject: [PATCH] Some proofreading + files renaming The files were renamed to match their (sometimes new) title. I'm only doing one pass of renaming, then we'll try to keep the names untouched so that they match l10n branches. --- contributing/_contributing.rst | 2 +- contributing/doc_and_l10n_guidelines.rst | 20 +- .../list_of_classes_and_documenters.rst | 2 + ...k.rst => updating_the_class_reference.rst} | 6 +- contributing/wiki_syntax.rst | 2 +- reference/_compiling.rst | 2 +- reference/_languages.rst | 2 +- ...bbcode.rst => bbcode_in_richtextlabel.rst} | 9 +- ...re_your_ide.rst => configuring_an_ide.rst} | 40 ++-- reference/creating_android_modules.rst | 4 +- reference/gdscript_more_efficiently.rst | 210 +++++++++--------- reference/inheritance_class_tree.rst | 2 +- reference/shading_language.rst | 4 +- 13 files changed, 159 insertions(+), 146 deletions(-) rename contributing/{reference_filling_work.rst => updating_the_class_reference.rst} (98%) rename reference/{richtextlabel_bbcode.rst => bbcode_in_richtextlabel.rst} (95%) rename reference/{configure_your_ide.rst => configuring_an_ide.rst} (65%) diff --git a/contributing/_contributing.rst b/contributing/_contributing.rst index b868180fd..b43dcea4f 100644 --- a/contributing/_contributing.rst +++ b/contributing/_contributing.rst @@ -8,5 +8,5 @@ Contributing bug_triage_guidelines doc_and_l10n_guidelines list_of_classes_and_documenters - reference_filling_work + updating_the_class_reference wiki_syntax diff --git a/contributing/doc_and_l10n_guidelines.rst b/contributing/doc_and_l10n_guidelines.rst index 9c40c879f..1c878c9da 100644 --- a/contributing/doc_and_l10n_guidelines.rst +++ b/contributing/doc_and_l10n_guidelines.rst @@ -1,13 +1,13 @@ .. _doc_doc_and_l10n_guidelines: -Documentation writing and translating guidelines -================================================ +Documentation and localisation guidelines +========================================= This page describes the rules to follow if you want to contribute Godot Engine by writing documentation or translating existing documentation. -What is a good documentation ? ------------------------------- +What is a good documentation? +----------------------------- A good documentation is well written in plain English and well-formed sentences. It is clear and objective. @@ -29,8 +29,10 @@ respect the following rules. Create a new wiki page ---------------------- +**TODO: Needs review for Sphinx doc** + Creating a new documentation page or tutorial page is easy. The -following rules must be respected : +following rules must be respected: - Choose a short and explicit title - Respect the grammar and orthography @@ -41,11 +43,15 @@ directly in another page or even forum posts using the include wiki syntax. For example, the syntax to include the page you are reading is : -!{{include(Documentation writing and translating guidelines)}}. +:: + + :ref:`the cool documentation guidelines ` Titles ~~~~~~ +**TODO: Needs review for Sphinx doc** + Please always begin pages with their name: ``h1. `` @@ -123,7 +129,7 @@ Important changes and discussions You are welcome to correct mistakes or styles to respect these guidelines. However, in case of important changes, please do not start a -discussion on this page : use the forum, create a new topic with a link +discussion on this page: use the forum, create a new topic with a link to the incriminated page and start discussing there about your remarks. Licence diff --git a/contributing/list_of_classes_and_documenters.rst b/contributing/list_of_classes_and_documenters.rst index 7d4a1976c..377b4ac62 100644 --- a/contributing/list_of_classes_and_documenters.rst +++ b/contributing/list_of_classes_and_documenters.rst @@ -3,6 +3,8 @@ List of classes and documenters =============================== +**TODO: Move out of the Sphinx doc, a pad would be better** + Status list : Not started, Started, Finished, Removed Class name - Assigned to - Status - Start date - Notes diff --git a/contributing/reference_filling_work.rst b/contributing/updating_the_class_reference.rst similarity index 98% rename from contributing/reference_filling_work.rst rename to contributing/updating_the_class_reference.rst index aebc436e7..8b13592d6 100644 --- a/contributing/reference_filling_work.rst +++ b/contributing/updating_the_class_reference.rst @@ -1,7 +1,7 @@ -.. _doc_reference_filling_work: +.. _doc_updating_the_class_reference: -Reference filling work -====================== +Updating the class reference +============================ Godot Engine provides an important number of classes that you can make use of to create your games. However, the :ref:`toc-class-ref` that diff --git a/contributing/wiki_syntax.rst b/contributing/wiki_syntax.rst index 5a9f456fb..a896e6775 100644 --- a/contributing/wiki_syntax.rst +++ b/contributing/wiki_syntax.rst @@ -1,6 +1,6 @@ .. _doc_wiki_syntax: -Wiki Syntax +Wiki syntax =========== This page is a helper for Wiki syntax. TODO. diff --git a/reference/_compiling.rst b/reference/_compiling.rst index 5de81275f..04801aef0 100644 --- a/reference/_compiling.rst +++ b/reference/_compiling.rst @@ -14,7 +14,7 @@ Compiling cross-compiling_for_ios_on_linux compiling_for_universal_windows_apps batch_building_templates - configure_your_ide + configuring_an_ide .. compiling_for_blackberry_qnx .. compiling_for_google_native_client diff --git a/reference/_languages.rst b/reference/_languages.rst index 3efde323c..d736b3a8f 100644 --- a/reference/_languages.rst +++ b/reference/_languages.rst @@ -9,4 +9,4 @@ Languages gdscript_more_efficiently shading_language locales - richtextlabel_bbcode + bbcode_in_richtextlabel diff --git a/reference/richtextlabel_bbcode.rst b/reference/bbcode_in_richtextlabel.rst similarity index 95% rename from reference/richtextlabel_bbcode.rst rename to reference/bbcode_in_richtextlabel.rst index 4e54a54c8..f9da2ba02 100644 --- a/reference/richtextlabel_bbcode.rst +++ b/reference/bbcode_in_richtextlabel.rst @@ -1,7 +1,7 @@ -.. _doc_richtextlabel_bbcode: +.. _doc_bbcode_in_richtextlabel: -BBCode RichTextLabel -==================== +BBCode in RichTextLabel +======================= Introduction ------------ @@ -9,6 +9,9 @@ Introduction :ref:`class_RichTextLabel` allows to display complex text markup in a control. It has a built-in API for generating the markup, but can also parse a BBCode. +Note that the BBCode tags can also be used to some extent in the +:ref:`XML source of the class reference `. + Setting up ---------- diff --git a/reference/configure_your_ide.rst b/reference/configuring_an_ide.rst similarity index 65% rename from reference/configure_your_ide.rst rename to reference/configuring_an_ide.rst index e8887c9d1..c5bcc6f4a 100644 --- a/reference/configure_your_ide.rst +++ b/reference/configuring_an_ide.rst @@ -1,9 +1,10 @@ -.. _doc_configure_your_ide: +.. _doc_configuring_an_ide: -Configure an IDE -================ +Configuring an IDE +================== -We assume that you already `cloned `_ and :ref:`compiled ` Godot. +We assume that you already `cloned `_ +and :ref:`compiled ` Godot. Kdevelop -------- @@ -78,29 +79,30 @@ QtCreator Importing the project ^^^^^^^^^^^^^^^^^^^^^ -* Choose *New Project* -> *Import Project* -> *Import Existing Project*. -* Set the path to your Godot root directory and enter the project name. -* Here you can choose which folders and files will be visible to the project. C/C++ files - are added automatically. Potentially useful additions: *.py for buildsystem files, *.java for Android development, - *.mm for OSX. Click "Next". -* Click *Finish*. +- Choose *New Project* -> *Import Project* -> *Import Existing Project*. +- Set the path to your Godot root directory and enter the project name. +- Here you can choose which folders and files will be visible to the project. C/C++ files + are added automatically. Potentially useful additions: \*.py for buildsystem files, \*.java for Android development, + \*.mm for OSX. Click "Next". +- Click *Finish*. Build and run ^^^^^^^^^^^^^ + Build configuration: -* Click on *Projects* and open the *Build* tab. -* Delete the pre-defined **make** build step. -* Click *Add Build Step* -> *Custom Process Step*. -* Type **scons** in the *Command* field. -* Fill the *Arguments* field with your compilation options. (e.g.: ``p=x11 target=debug -j 4``) +- Click on *Projects* and open the *Build* tab. +- Delete the pre-defined ``make`` build step. +- Click *Add Build Step* -> *Custom Process Step*. +- Type ``scons`` in the *Command* field. +- Fill the *Arguments* field with your compilation options. (e.g.: ``p=x11 target=debug -j 4``) Run configuration: -* Open the *Run* tab. -* Point the *Executable* to your compiled Godot binary. -* If you want to run a specific game or project, point *Working directory* to the game directory. -* If you want to run the editor, add **-e** to the *Command line arguments* field. +- Open the *Run* tab. +- Point the *Executable* to your compiled Godot binary. +- If you want to run a specific game or project, point *Working directory* to the game directory. +- If you want to run the editor, add ``-e`` to the *Command line arguments* field. Other editors (vim, emacs, Atom...) ----------------------------------- diff --git a/reference/creating_android_modules.rst b/reference/creating_android_modules.rst index 3a86d8c60..f6b3486b1 100644 --- a/reference/creating_android_modules.rst +++ b/reference/creating_android_modules.rst @@ -261,10 +261,10 @@ sequence: c:\godot> scons p=android c:\godot\platform\android\java> ant release -Using the Module +Using the module ~~~~~~~~~~~~~~~~ -To use the Module from GDScript, first enable the singleton by adding +To use the module from GDScript, first enable the singleton by adding the following line to engine.cfg: :: diff --git a/reference/gdscript_more_efficiently.rst b/reference/gdscript_more_efficiently.rst index ebee23f79..fdc6d1649 100644 --- a/reference/gdscript_more_efficiently.rst +++ b/reference/gdscript_more_efficiently.rst @@ -1,7 +1,7 @@ .. _doc_gdscript_more_efficiently: -Using GDScript Efficiently -========================== +GDScript more efficiently +========================= About ----- @@ -13,10 +13,10 @@ also covers a lot related to using dynamically typed languages. It's meant to be specially useful for programmers without previous or little experience of dynamically typed languages. -Dynamic Nature +Dynamic nature -------------- -Pros & Cons of Dynamic Typing +Pros & cons of dynamic typing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GDScript is a Dynamically Typed language. As such, it's main advantages @@ -48,7 +48,7 @@ possibility of using C++ is present too. This allows to still create the entire game in GDScript and add small bits of C++ in the areas that need a boost. -Variables & Assignment +Variables & assignment ~~~~~~~~~~~~~~~~~~~~~~ All variables in a dynamically typed language are "variant"-like. This @@ -60,18 +60,18 @@ Static: :: int a; // value uninitialized - a=5; // this is valid - a="Hi!"; // this is invalid + a = 5; // this is valid + a = "Hi!"; // this is invalid Dynamic: :: var a # null by default - a=5 # valid, 'a' becomes an integer - a="Hi!" # valid, 'a' changed to a string + a = 5 # valid, 'a' becomes an integer + a = "Hi!" # valid, 'a' changed to a string -As Function Arguments: +As function arguments: ~~~~~~~~~~~~~~~~~~~~~~ Functions are of dynamic nature too, which means they can be called with @@ -83,7 +83,7 @@ Static: void print_value(int value) { - printf("value is %i\\n",value); + printf("value is %i\n",value); } [..] @@ -102,7 +102,7 @@ Dynamic: print_value(55) # valid print_value("Hello") # valid -Pointers & Referencing: +Pointers & referencing: ~~~~~~~~~~~~~~~~~~~~~~~ In static languages such as C or C++ (and to some extent Java and C#), @@ -116,9 +116,9 @@ garbage-collected automatically, which means they are erased when no onger used. Dynamically typed languages tend to use this memory model too. Some Examples: -// C++ +- C++: -:: +.. code:: cpp void use_class(SomeClass *instance) { @@ -127,14 +127,14 @@ too. Some Examples: void do_something() { - SomeClass *instance = new SomeClass; //created as pointer - use_class(instance); //pass as pointer - delete instance; //otherwise it will leak memory + SomeClass *instance = new SomeClass; // created as pointer + use_class(instance); // passed as pointer + delete instance; // otherwise it will leak memory } -Java: +- Java: -:: +.. code:: java @Override public final void use_class(SomeClass instance) { @@ -144,23 +144,23 @@ Java: public final void do_something() { - SomeClass instance = new SomeClass(); //created as reference - use_class(instance); //pass as reference - //garbage collector will get rid of it when not in - //use and freeze your game randomly for a second + SomeClass instance = new SomeClass(); // created as reference + use_class(instance); // passed as reference + // garbage collector will get rid of it when not in + // use and freeze your game randomly for a second } -GDScript: +- GDScript: :: - func use_class(instance); #does not care about class type + func use_class(instance); # does not care about class type instance.use() # will work with any class that has a ".use()" method. func do_something(): var instance = SomeClass.new() # created as reference - use_class(instance) # pass as reference - #will be unreferenced and deleted + use_class(instance) # passed as reference + # will be unreferenced and deleted In GDScript, only base types (int, float, string and the vector types) are passed by value to functions (value is copied). Everything else @@ -174,41 +174,39 @@ Arrays Arrays in dynamically typed languages can contain many different mixed datatypes inside and are always dynamic (can be resized at any time). -Example: +Compare for example arrays in statically typed languages: :: - int *array = new int[4]; //create array - array[0]=10; //initialize manually - array[1]=20; //can't mix types - array[2]=40; - array[3]=60; - //can't resize - use_array(array); //passed as pointer - delete[] array; //must be freed + int *array = new int[4]; // create array + array[0] = 10; // initialize manually + array[1] = 20; // can't mix types + array[2] = 40; + array[3] = 60; + // can't resize + use_array(array); // passed as pointer + delete[] array; // must be freed -//or - -:: + //or std::vector array; array.resize(4); - array[0]=10; //initialize manually - array[1]=20; //can't mix types - array[2]=40; - array[3]=60; - array.resize(3); //can be resized - use_array(array); //passed reference or value - //freed when stack ends + array[0] = 10; // initialize manually + array[1] = 20; // can't mix types + array[2] = 40; + array[3] = 60; + array.resize(3); // can be resized + use_array(array); // passed reference or value + // freed when stack ends -GDScript: +And in GDScript: :: var array = [10, "hello", 40, 60] # simple, and can mix types array.resize(3) # can be resized use_array(array) # passed as reference - #freed when no longer in use + # freed when no longer in use In dynamically typed languages, arrays can also double as other datatypes, such as lists: @@ -220,13 +218,13 @@ datatypes, such as lists: array.append(5) array.pop_front() -or unordered sets: +Or unordered sets: :: var a = 20 - if a in [10,20,30]: - print("We have a Winner!") + if a in [10, 20, 30]: + print("We have a winner!") Dictionaries ------------ @@ -247,51 +245,51 @@ Example of Dictionary: :: - var d = { "name":"john", "age":22 } # simple syntax - print("Name: ", d["name"], " Age: ", d["age"] ) + var d = { "name": "john", "age": 22 } # simple syntax + print("Name: ", d["name"], " Age: ", d["age"]) Dictionaries are also dynamic, keys can be added or removed at any point at little cost: :: - d["mother"]="Rebecca" # addition - d["age"]=11 # modification - d.erase("name") #removal + d["mother"] = "Rebecca" # addition + d["age"] = 11 # modification + d.erase("name") # removal In most cases, two-dimensional arrays can often be implemented more easily with dictionaries. Here's a simple battleship game example: :: - #battleship game + # battleship game - const SHIP=0 - const SHIP_HIT=1 - const WATER_HIT=2 + const SHIP = 0 + const SHIP_HIT = 1 + const WATER_HIT = 2 - var board={} + var board = {} func initialize(): - board[Vector(1,1)]=SHIP - board[Vector(1,2)]=SHIP - board[Vector(1,3)]=SHIP + board[Vector(1,1)] = SHIP + board[Vector(1,2)] = SHIP + board[Vector(1,3)] = SHIP func missile(pos): - if pos in board: #something at that pos - if board[pos]==SHIP: #there was a ship! hit it - board[pos]=SHIP_HIT + if pos in board: # something at that pos + if board[pos] == SHIP: # there was a ship! hit it + board[pos] = SHIP_HIT else: print("already hit here!") # hey dude you already hit here - else: #nothing, mark as water - board[pos]=WATER_HIT + else: # nothing, mark as water + board[pos] = WATER_HIT func game(): initialize() - missile( Vector2(1,1) ) - missile( Vector2(5,8) ) - missile( Vector2(2,3) ) + missile(Vector2(1,1)) + missile(Vector2(5,8)) + missile(Vector2(2,3)) Dictionaries can also be used as data markup or quick structures. While GDScript dictionaries resemble python dictionaries, it also supports Lua @@ -303,20 +301,20 @@ states and quick structs: # same example, lua-style support # this syntax is a lot more readable and usable - var d = { - name="john", - age=22 - } + var d = { + name = "john", + age = 22 + } - print("Name: ", d.name, " Age: ", d.age ) # used "." based indexing + print("Name: ", d.name, " Age: ", d.age) # used "." based indexing # indexing - d.nother="rebecca" #this doesn't work (use syntax below to add a key:value pair) - d["mother"]="rebecca" #this works - d.name="caroline" # if key exists, assignment does work, this is why it's like a quick struct. + d.mother = "rebecca" # this doesn't work (use syntax below to add a key:value pair) + d["mother"] = "rebecca" # this works + d.name = "caroline" # if key exists, assignment does work, this is why it's like a quick struct. -For & While +For & while ----------- Iterating in some statically typed languages can be quite complex: @@ -327,15 +325,15 @@ Iterating in some statically typed languages can be quite complex: [..] - for(int i=0;i<50;i++) + for(int i=0; i<50; i++) { - printf("value: %s\\n",i,strings[i]); + printf("value: %s\n", i, strings[i]); } - //Even in STL: + // even in STL: - for(std::list::const_iterator it = strings.begin() ; it != strings.end() ; it++) { + for(std::list::const_iterator it = strings.begin(); it != strings.end(); it++) { std::cout << *it << std::endl; } @@ -353,7 +351,7 @@ allow iterating the keys: :: for key in dict: - print(key," -> ",dict[key]) + print(key, " -> ", dict[key]) Iterating with indices is also possible: @@ -367,18 +365,18 @@ The range() function can take 3 arguments: :: range(n) (will go from 0 to n-1) - range(b,n) (will go from b to n-1) - range(b,n,s) (will go from b to n-1, in steps of s) + range(b, n) (will go from b to n-1) + range(b, n, s) (will go from b to n-1, in steps of s) Some examples: :: - for(int i=0;i<10;i++) {} + for(int i=0; i<10; i++) {} - for(int i=5;i<10;i++) {} + for(int i=5; i<10; i++) {} - for(int i=5;i<10;i+=2) {} + for(int i=5; i<10; i+=2) {} Translate to: @@ -386,43 +384,45 @@ Translate to: for i in range(10): - for i in range(5,10): + for i in range(5, 10): - for i in range(5,10,2): + for i in range(5, 10, 2): And backwards looping is done through a negative counter: :: - for(int i=10;i>0;i--) {} + for(int i=10; i>0; i--) {} becomes :: - for i in range(10,0,-1): + for i in range(10, 0, -1): While ----- -While() loops are the same everywhere: +while() loops are the same everywhere: :: - var i=0 + var i = 0 - while(i + while(i < strings.size()): + print(strings[i]) + i += 1 -Duck Typing +Duck typing ----------- One of the most difficult concepts to grasp when moving from a -statically typed language to a dynamic one is Duck Typing. Duck typing +statically typed language to a dynamic one is duck typing. Duck typing makes overall code design much simpler and straightforward to write, but it's not obvious how it works. As an example, imagine a situation where a big rock is falling down a -tunnel, smashing everything on it's way. The code for the rock, in a +tunnel, smashing everything on its way. The code for the rock, in a statically typed language would be something like: :: @@ -437,12 +437,12 @@ inherit Smashable. If a character, enemy, piece of furniture, small rock were all smashable, they would need to inherit from the class Smashable, possibly requiring multiple inheritance. If multiple inheritance was undesired, then they would have to inherit a common class like Entity. -Yet, it would not be very elegant to add a virtual method "smash()" to +Yet, it would not be very elegant to add a virtual method ``smash()`` to Entity only if a few of them can be smashed. With dynamically typed languages, this is not a problem. Duck typing -makes sure you only have to define a smash() function where required and -that's it. No need to consider inheritance, base classes, etc. +makes sure you only have to define a ``smash()`` function where required +and that's it. No need to consider inheritance, base classes, etc. :: @@ -472,7 +472,7 @@ checking if the function exists is desirable: func _on_object_hit(object): if (object.has_method("smash")): - object.smash() + object.smash() Then, simply define that method and anything the rock touches can be smashed. diff --git a/reference/inheritance_class_tree.rst b/reference/inheritance_class_tree.rst index dfc6ee427..8bf3b0e67 100644 --- a/reference/inheritance_class_tree.rst +++ b/reference/inheritance_class_tree.rst @@ -1,4 +1,4 @@ -Inheritance Class Tree +Inheritance class tree ====================== Object diff --git a/reference/shading_language.rst b/reference/shading_language.rst index 191ee6941..95c01d77c 100644 --- a/reference/shading_language.rst +++ b/reference/shading_language.rst @@ -1,6 +1,6 @@ .. _doc_shading_language: -Shading Language +Shading language ================ Introduction @@ -25,7 +25,7 @@ The language is statically type and supports only a few operations. Arrays, classes, structures, etc are not supported. Several built-in datatypes are provided: -Data Types +Data types ~~~~~~~~~~ +-------------------+--------------------------------------------------------------+