Fix various Sphinx warnings

community/contributing/code_style_guidelines.rst

@@ -15,7 +15,7 @@ C++ and Objective-C
 -------------------
 
 There are no written guidelines, but the code style agreed upon by the
-developers is enforced via the `clang-format <http://clang.llvm.org/docs/ClangFormat.html>`_
+developers is enforced via the `clang-format <http://clang.llvm.org/docs/ClangFormat.html>`__
 code beautifier, which takes care for you of all our conventions.
 To name a few:
 
@@ -25,7 +25,7 @@ To name a few:
   to the type name
 
 The rules used by clang-format are outlined in the
-`.clang-format <https://github.com/godotengine/godot/blob/master/.clang-format>`_
+`.clang-format <https://github.com/godotengine/godot/blob/master/.clang-format>`__
 file of the Godot repository.
 
 As long as you ensure that your style matches the surrounding code and that you
@@ -62,7 +62,7 @@ Here's how to install clang-format:
 - Linux: It will usually be available out-of-the-box with the clang toolchain
   packaged by your distribution.
 - macOS and Windows: You can download precompiled binaries from the
-  `LLVM website <http://llvm.org/releases/download.html>`_. You may need to add
+  `LLVM website <http://llvm.org/releases/download.html>`__. You may need to add
   the path to the binary's folder to your system's ``PATH`` environment
   variable to be able to call ``clang-format`` out of the box.
 
@@ -76,13 +76,10 @@ command:
 
 ::
 
-    clang-format -i -style=file <path/to/file(s)>
+    clang-format -i <path/to/file(s)>
 
 - ``-i`` means that the changes should be written directly to the file (by
   default clang-format would only output the fixed version to the terminal).
-- ``-style=file`` tells clang-format to use the ``.clang-format`` file of
-  Godot's repository as a style guide. Note that the ``file`` part is the
-  actual "file" word, not a path to a file.
 - The path can point to several files, either one after the other or using
   wildcards like in a typical Unix shell. Be careful when globbing so that
   you don't run clang-format on compiled objects (.o and .a files) that are
@@ -111,9 +108,9 @@ clang-format automatically, for example each time you save a file.
 
 Here is a non-exhaustive list of beautifier plugins for some IDEs:
 
-- Qt Creator: `Beautifier plugin <http://doc.qt.io/qtcreator/creator-beautifier.html>`_
-- Visual Studio Code: `Clang-Format <https://marketplace.visualstudio.com/items?itemName=xaver.clang-format>`_
-- vim: `vim-clang-format <https://github.com/rhysd/vim-clang-format>`_
+- Qt Creator: `Beautifier plugin <http://doc.qt.io/qtcreator/creator-beautifier.html>`__
+- Visual Studio Code: `Clang-Format <https://marketplace.visualstudio.com/items?itemName=xaver.clang-format>`__
+- vim: `vim-clang-format <https://github.com/rhysd/vim-clang-format>`__
 
 (Pull requests welcome to extend this list with tested plugins.)
 
@@ -131,7 +128,7 @@ Python
 Godot's SCons buildsystem is written in Python 2, and various scripts included
 in the source tree are either in Python 2 or Python 3.
 
-For those, we follow the `PEP-8 style guide <https://www.python.org/dev/peps/pep-0008/>`_,
+For those, we follow the `PEP-8 style guide <https://www.python.org/dev/peps/pep-0008/>`__,
 this is however not as strongly enforced as for the C++ code. If you are so
 inclined, you can check and format your Python changes using
-`autopep8 <https://pypi.python.org/pypi/autopep8>`_.
+`autopep8 <https://pypi.python.org/pypi/autopep8>`__.

learning/editor/unity_to_godot.rst

@@ -15,7 +15,7 @@ Differences
 +-------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------+
 |                   | Unity                                                                             | Godot                                                                                                          |
 +===================+===================================================================================+================================================================================================================+
-| License           | Proprietary, closed, free license with revenue caps and usage restrictions        | MIT License,  free and fully open source without any restriction                                                |
+| License           | Proprietary, closed, free license with revenue caps and usage restrictions        | MIT license, free and fully open source without any restriction                                                |
 +-------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------+
 | OS (editor)       | Windows, OSX, Linux (unofficial and unsupported)                                  | Windows, X11 (Linux, \*BSD), Haiku, OSX                                                                        |
 +-------------------+-----------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------+
@@ -177,11 +177,9 @@ You can control nodes by accessing them using a script, and call functions (buil
 But there's more! Certain nodes throw signals when certain actions happen. You can connect these signals to call a specific function when they happen. Note that you can define your own signals and send them whenever you want. This feature is documented `here <gdscript.html#signals>`_.
 
 
-
 Using Godot in C++
 ------------------
 
 Just for your information, Godot also allows you to develop your project directly in C++ by using its API, which is not possible with Unity at the moment. As an example, you can consider Godot Engine's editor as a "game" written in C++ using Godot API. 
 
 If you are interested in using Godot in C++, you may want to start reading the `Developing in C++ <_developing.html>`_ page.
-

learning/features/3d/index.rst

@@ -8,6 +8,6 @@
    introduction_to_3d
    3d_performance_and_limitations
    spatial_material
-   shader_material
+   shader_materials
    high_dynamic_range
    using_gridmaps

learning/features/3d/introduction_to_3d.rst

@@ -170,7 +170,7 @@ this little menu inside the window because it is often overlooked!
 .. image:: img/tuto_3d6.png
 
 Default environment
-----------------
+-------------------
 
 When created from the Project Manager, the 3D environment has a default sky.
 
@@ -215,4 +215,3 @@ Lights
 
 There is no limitation on the number of lights nor of types of lights in
 Godot. As many as desired can be added (as long as performance allows). 
-

learning/features/3d/spatial_material.rst

@@ -1,7 +1,7 @@
 .. _doc_spatial_material:
 
 Spatial Material
-===============
+================
 
 Introduction
 ------------
@@ -68,7 +68,7 @@ Additionaly, on very low end devices such as mobile, switching to vertex lightin
 Keep in mind that, when vertex lighting is enabled, only directional lighting can produce shadows (for performance reasons).
 
 No Depth Test
-~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~
 
 In order for close objects to appear over far away objects, depth testing is performed.
 Disabling it has the result of objects appearing over (or under) everything else.
@@ -179,8 +179,8 @@ Specifies when depth rendering must take place.
 * Opaque Only (default): Depth is only drawn for opaque objects
 * Always: Depth draw is drawn for both opaque and transparent objects
 * Never: No depth draw takes place (note: do not confuse with depth test option above)
-* Depth Pre-Pass: For transparent objects, an opaque pass is made first with the opaque parts, then tranparency is drawn above. Use this option
-with transparent grass or tree foliage.
+* Depth Pre-Pass: For transparent objects, an opaque pass is made first with the opaque parts,
+  then tranparency is drawn above. Use this option with transparent grass or tree foliage.
 
 .. image:: img/material_depth_draw.png
 
@@ -389,5 +389,3 @@ Render Priority
 ---------------
 
 Rendering order can be changed for objects, although this is mostly useful for transparent ojects (or opaque objects that do depth draw but no color draw, useful for cracks on the floor).
-
-

learning/features/shading/screen-reading_shaders.rst

@@ -117,7 +117,7 @@ Godot:
 
 
 DEPTH_TEXTURE
-~~~~~~~~~~~~
+~~~~~~~~~~~~~
 
 For 3D Shaders, it's also possible to access the screen depth buffer. For this,
 the DEPTH_TEXTURE built-in is used. This texture is not linear, it must be
@@ -130,6 +130,3 @@ The following code retrieves the 3D position below the pixel being drawn:
 	float depth = textureLod(DEPTH_TEXTURE,SCREEN_UV,0.0).r;
 	vec4 upos = INV_PROJECTION_MATRIX * vec4(SCREEN_UV*2.0-1.0,depth*2.0-1.0,1.0);
 	vec3 pixel_position = upos.xyz/upos.w;
-
-
-

learning/features/shading/shading_language.rst

@@ -40,7 +40,7 @@ be after the *shader_type*. Example syntax is:
 .. code-block:: glsl
 
     shader_type spatial;
-	render_mode unshaded,cull_disabled;
+    render_mode unshaded, cull_disabled;
 
 Data types:
 -----------
@@ -140,10 +140,10 @@ Construction of vector types must always pass:
     // The required amount of scalars
     vec4 a = vec4(0.0, 1.0, 2.0, 3.0);
     // Complementary vectors and/or scalars
-	vec4 a = vec4( vec2(0.0, 1.0), vec2(2.0, 3.0) );
-	vec4 a = vec4( vec3(0.0, 1.0, 2.0), 3.0 );
+    vec4 a = vec4(vec2(0.0, 1.0), vec2(2.0, 3.0));
+    vec4 a = vec4(vec3(0.0, 1.0, 2.0), 3.0);
     // A single scalar for the whole vector
-	vec4 a = vec4( 0.0 );
+    vec4 a = vec4(0.0);
 
 Swizzling
 ~~~~~~~~~
@@ -191,7 +191,7 @@ Godot shading language supports the same set of operators as GLSL ES 3.0. Below
 +-------------+-----------------------+--------------------+
 | 2           | unary                 | **+, -, !, ~**     |
 +-------------+-----------------------+--------------------+
-| 3           | multiplicative        | **/, *, % **       |
+| 3           | multiplicative        | **/, \*, %**       |
 +-------------+-----------------------+--------------------+
 | 4           | additive              | **+, -**           |
 +-------------+-----------------------+--------------------+
@@ -219,19 +219,19 @@ Godot Shading language supports the most common types of flow control:
 
 .. code-block:: glsl
 
-	//if and else
+    // if and else
     if (cond) {
 
     } else {
 
     }
 
-	//for loops
-	for(int i=0;i<10;i++) {
+    // for loops
+    for     (int i = 0; i < 10; i++) {
 
     }
 
-	//whiles
+    // while
     while (true) {
 
     }
@@ -260,7 +260,7 @@ It's possible to define any function in a Godot shader. They take the following
     // a better example:
 
     int sum2(int a, int b) {
-		return a+b;
+        return a + b;
     }
 
 
@@ -277,7 +277,7 @@ Example below:
 .. code-block:: glsl
 
     void sum2(int a, int b, inout int result) {
-		result = a+b;
+        result = a + b;
     }
 
 
@@ -303,7 +303,7 @@ vertex functions are not that commonly used.
     shader_type spatial;
 
     void vertex() {
-		VERTEX.x+=sin(TIME); //offset vertex x by sine function on time elapsed
+        VERTEX.x += sin(TIME); // offset vertex x by sine function on time elapsed
     }
 
 
@@ -318,7 +318,7 @@ runs on every visible pixel the object or primitive is drawn to.
     shader_type spatial;
 
     void fragment() {
-		ALBEDO=vec3(1.0,0.0,0.0); // use red for material albedo
+        ALBEDO = vec3(1.0, 0.0, 0.0); // use red for material albedo
     }
 
 Light Processor
@@ -332,7 +332,7 @@ and does not run if no lights affect the object).
     shader_type spatial;
 
     void light() {
-		COLOR=vec3(0.0,1.0,0.0); 
+        COLOR = vec3(0.0, 1.0, 0.0);
     }
 
 
@@ -380,7 +380,7 @@ to make the compiler understand what the uniform is used for.
     shader_type spatial;
 
     uniform vec4 color : hint_color;
-	uniform float amount : hint_range(0,1);
+    uniform float amount : hint_range(0, 1);
 
 
 Full list of hints below:
@@ -429,8 +429,6 @@ A large number of built-in functions are supported, conforming mostly to GLSL ES
 When vec_type (float), vec_int_type, vec_uint_type, vec_bool_type nomenclature is used, it can be scalar or vector.
 
 
-
-
 +-----------------------------------------------------------------------+---------------------------------------------+
 | Function                                                              | Description                                 |
 +=======================================================================+=============================================+
@@ -584,7 +582,7 @@ When vec_type (float), vec_int_type, vec_uint_type, vec_bool_type nomenclature i
 
 
 Shader Types In-Depth
-------------------
+---------------------
 
 Spatial
 ~~~~~~~
@@ -711,9 +709,9 @@ happen later, though) with the following code, so it can be done manually:
 
     void vertex() {
 
-		VERTEX = (MODELVIEW_MATRIX * vec4(VERTEX,1.0)).xyz;
-		NORMAL = (MODELVIEW_MATRIX * vec4(VERTEX,0.0)).xyz; 
-		//same as above for binormal and tangent, if normal mapping is used
+        VERTEX = (MODELVIEW_MATRIX * vec4(VERTEX, 1.0)).xyz;
+        NORMAL = (MODELVIEW_MATRIX * vec4(VERTEX, 0.0)).xyz;
+        // same as above for binormal and tangent, if normal mapping is used
     }
 
 
@@ -937,7 +935,7 @@ happen later, though) with the following code, so it can be done manually:
 
     void vertex() {
 
-		VERTEX = (EXTRA_MATRIX * (WORLD_MATRIX * vec4(VERTEX,0.0,1.0))).xy;
+        VERTEX = (EXTRA_MATRIX * (WORLD_MATRIX * vec4(VERTEX, 0.0, 1.0))).xy;
     }
 
 
@@ -1079,6 +1077,3 @@ Vertex Built-Ins
 
 Particle shades only support vertex processing. They are drawn with any regular material for CanvasItem or Spatial, depending on
 whether they are 2D or 3D.
-
-
-

learning/step_by_step/scripting.rst

@@ -34,8 +34,7 @@ to the high integration with Godot:
 * The editor integration is a pleasure to work with, with code completion expanding as far as completing nodes, signals, and many other items pertaining to the current scene being edited.
 * Has vector types built-in (such as Vectors, transorms etc), making it efficient for heavy linear algebra.
 * It supports multiple threads as well as statically typed languages (which is one of the limitation that avoided us going for other VMs such as Lua, Squirrel, etc).
-* It uses no garbage collector, so it trades a small bit of automation (most
-objects are reference counted anyway), by determinism.
+* It uses no garbage collector, so it trades a small bit of automation (most objects are reference counted anyway), by determinism.
 * The dynamic nature of it makes it easy to optimize chunks of it in C++ (via GDNative) if more performance is required at some point, without recompiling the engine.
 
 If undecided, and have experience in programming (specially dynamically

learning/workflow/assets/importing_images.rst

@@ -1,7 +1,7 @@
 .. _doc_import_images:
 
 Importing Images
-==============
+================
 
 Why importing them?
 -------------------
@@ -34,11 +34,11 @@ Compress Mode
 ~~~~~~~~~~~~~
 
 * VRAM Compression: This is the most common copression mode for 3D assets. File on disk is reduced and
-video memory usage is also reduced considerably. For 3D, it may present unwanted arctifacts, though.
+  video memory usage is also reduced considerably. For 3D, it may present unwanted arctifacts, though.
 * Lossless Compression: This is the most common compression for 2D assets. It shows assets without any
-kind of arctifacting, and disk compression is decent. It will use considerably more amount of video memory than VRAM, though.
+  kind of arctifacting, and disk compression is decent. It will use considerably more amount of video memory than VRAM, though.
 * Lossy Compression: For games with lots of large 2D assets, lossy compression can be a great choice. It has some arctifacting,
-but less than VRAM and the file size is almost a tenth of Lossless.
+  but less than VRAM and the file size is almost a tenth of Lossless.
 * Uncompressed: Only useful for formats that can't be compressed (like, raw float).
 
 In this table, each of the four options are described together with their
@@ -60,6 +60,11 @@ advantages and disadvantages ( |good| = Best, |bad| =Worst ):
 | Load Time      | |regular| Normal       | |bad| Slow                | |bad| Slow              | |good| Fast                                          |
 +----------------+------------------------+---------------------------+-------------------------+------------------------------------------------------+
 
+.. |bad| image:: img/bad.png
+
+.. |good| image:: img/good.png
+
+.. |regular| image:: img/regular.png
 
 HDR Mode
 ~~~~~~~~
@@ -150,7 +155,3 @@ Detect 3D
 
 This option makes Godot be aware of when a texture (which is imported for 2D as default) is used in 3D. If this happens, setting are changed so the texture flags
 are friendlier to 3D (mipmaps, filter and repeat become enabled and compression is changed to VRAM). Texture is also reimported automaticlaly.
-
-
-
-

learning/workflow/assets/importing_scenes.rst

@@ -1,7 +1,7 @@
 .. _doc_importing_3d_scenes:
 
 Importing 3D Scenes
-==================
+===================
 
 Godot Scene Importer
 --------------------
@@ -250,7 +250,7 @@ objects in your 3D modelling software. When imported, Godot will detect them and
 actions automatically:
 
 Remove nodes (-noimp)
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~
 
 Node names that have this suffix will be removed at import time, mo
 matter what their type is. They will not appear in the imported scene.