godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-03 05:48:42 +03:00
Code Issues Packages Projects Releases Wiki Activity

Some proofreading + files renaming

Browse Source 
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.
This commit is contained in:
Rémi Verschelde
2016-02-19 20:15:14 +01:00
parent 2503364927
commit 1b0aff29aa
13 changed files with 159 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
contributing/_contributing.rst
View File

@@ -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

20
contributing/doc_and_l10n_guidelines.rst
View File

@@ -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 <doc_doc_and_l10n_guidelines>`
Titles
~~~~~~
**TODO: Needs review for Sphinx doc**
Please always begin pages with their name:
``h1. <Insert your title here>``
@@ -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

2
contributing/list_of_classes_and_documenters.rst
View File

@@ -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

6
contributing/reference_filling_work.rst → contributing/updating_the_class_reference.rst
View File

@@ -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

2
contributing/wiki_syntax.rst
View File

@@ -1,6 +1,6 @@
.. _doc_wiki_syntax:
Wiki Syntax
Wiki syntax
===========
This page is a helper for Wiki syntax. TODO.

2
reference/_compiling.rst
View File

@@ -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

2
reference/_languages.rst
View File

@@ -9,4 +9,4 @@ Languages
gdscript_more_efficiently
shading_language
locales
richtextlabel_bbcode
bbcode_in_richtextlabel

9
reference/richtextlabel_bbcode.rst → reference/bbcode_in_richtextlabel.rst
View File

@@ -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 <doc_updating_the_class_reference>`.
Setting up
----------

40
reference/configure_your_ide.rst → reference/configuring_an_ide.rst
View File

@@ -1,9 +1,10 @@
.. _doc_configure_your_ide:
.. _doc_configuring_an_ide:
Configure an IDE
================
Configuring an IDE
==================
We assume that you already `cloned <https://github.com/godotengine/godot>`_ and :ref:`compiled <toc-compiling>` Godot.
We assume that you already `cloned <https://github.com/godotengine/godot>`_
and :ref:`compiled <toc-compiling>` 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...)
-----------------------------------

4
reference/creating_android_modules.rst
View File

@@ -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:
::

210
reference/gdscript_more_efficiently.rst
View File

@@ -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<int> 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<std::string>::const_iterator it = strings.begin() ; it != strings.end() ; it++) {
for(std::list<std::string>::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.

2
reference/inheritance_class_tree.rst
View File

@@ -1,4 +1,4 @@
Inheritance Class Tree
Inheritance class tree
======================
Object

4
reference/shading_language.rst
View File

@@ -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
~~~~~~~~~~
+-------------------+--------------------------------------------------------------+