Adjusted language and layout of configuring an IDE docs

_static/css/custom.css

@@ -212,6 +212,14 @@ legend,
     opacity: 0.75;
 }
 
+.rst-content div.figure.figure-w480 {
+    max-width: 480px;
+}
+
+.rst-content div.figure img {
+    border: 1px solid var(--body-color);
+}
+
 p,
 article ul,
 article ol,

development/cpp/configuring_an_ide/android_studio.rst

@@ -8,12 +8,19 @@ Android Studio
 It has a feature-rich editor which supports Java and C/C++. It can be used to
 work on Godot's core engine as well as the Android platform codebase.
 
-- From Android Studio's welcome window, select
-  **Open an existing Android Studio project**.
+Importing the project
+---------------------
 
-.. image:: img/android_studio_setup_project_1.png
+- From the Android Studio's welcome window select **Open an existing 
+  Android Studio project**.
 
-- Navigate to ``<Godot root directory>/platform/android/java`` and select the ``settings.gradle`` gradle file.
+.. figure:: img/android_studio_setup_project_1.png
+   :figclass: figure-w480
+   :align: center
+   
+   Android Studio's welcome window.
+
+- Navigate to ``<Godot root directory>/platform/android/java`` and select the ``settings.gradle`` file.
 - Android Studio will import and index the project.
 - To build the project, follow the :ref:`compiling instructions <toc-devel-compiling>`.
 

development/cpp/configuring_an_ide/clion.rst

@@ -3,29 +3,39 @@
 CLion
 =====
 
-`CLion <https://www.jetbrains.com/clion/>`_ is a commercial IDE for C++.
-It requires a ``CMakeLists.txt`` file as a project file, which is problematic
-for Godot which uses the SCons buildsystem instead of CMake.
-However, there is a ``CMakeLists.txt`` configuration for
-:ref:`Android Studio <doc_configuring_an_ide_android_studio>` which can also
-be used by CLion.
-
-- If you've already opened another project, choose **File > Open** at the top of
-  the CLion window. Otherwise, choose the option to import an existing project
-  in the Welcome window.
-- Navigate to your Godot Git clone then select the folder
-  ``platform/android/java/lib`` - the ``CMakeLists.txt`` file is located there.
-  Select the folder (*not* the ``CMakeLists.txt file``), then click **OK**.
-
-.. image:: img/clion_1_open.png
+`CLion <https://www.jetbrains.com/clion/>`_ is a commercial 
+`JetBrains <https://www.jetbrains.com/>`_ IDE for C++.
+
+Importing the project
+---------------------
+
+CLion requires a ``CMakeLists.txt`` file as a project file, which is problematic
+for Godot because it uses the SCons buildsystem instead of CMake. However, 
+there is a ``CMakeLists.txt`` configuration for :ref:`Android Studio <doc_configuring_an_ide_android_studio>` 
+which can also be used by CLion.
+
+- From the CLion's welcome window choose the option to import an existing 
+  project. If you've already opened another project, choose **File > Open**
+  from the top menu.
+- Navigate to ``<Godot root directory>/platform/android/java/lib`` (the 
+  ``CMakeLists.txt`` file is located there) and select it (but *not* the
+  ``CMakeLists.txt`` file itself), then click **OK**.
+
+.. figure:: img/clion_1_open.png
+   :align: center
+
+   The folder containing the ``CMakeLists.txt`` file.
 
 - If this popup window appears, select **This Window** to open the project:
 
-.. image:: img/clion_2_this_window.png
+.. figure:: img/clion_2_this_window.png
+   :align: center
 
-- Choose **Tools > CMake >Change Project Root** and select the root Godot folder.
+- Choose **Tools > CMake > Change Project Root** from the top menu and select 
+  the Godot root folder.
 
-.. image:: img/clion_3_change_project_root.png
+.. figure:: img/clion_3_change_project_root.png
+   :align: center
 
 - You should be now be able to see all the project files. Autocomplete should
   work once the project has finished indexing.

development/cpp/configuring_an_ide/index.rst

@@ -16,8 +16,8 @@ Development Environment), here are setup instructions for some popular ones:
    clion
    kdevelop
    qt_creator
-   visual_studio_code
    visual_studio
+   visual_studio_code
    xcode
 
 It is possible to use other IDEs, but their setup is not documented yet.

development/cpp/configuring_an_ide/kdevelop.rst

@@ -5,54 +5,83 @@ KDevelop
 
 `KDevelop <https://www.kdevelop.org>`_ is a free, open source IDE for all desktop platforms.
 
-Start by opening KDevelop and choosing **Open Project**.
+Importing the project
+---------------------
 
-.. image:: img/kdevelop_newproject.png
+- From the KDevelop's main screen select **Open Project**.
 
-Choose the directory where you cloned Godot.
+.. figure:: img/kdevelop_newproject.png
+   :figclass: figure-w480
+   :align: center
 
-On the next screen, choose **Custom Build System** for the **Project Manager**.
+   KDevelop's main screen.
 
-.. image:: img/kdevelop_custombuild.png
+- Navigate to the Godot root folder and select it.
+- On the next screen, choose **Custom Build System** for the **Project Manager**.
 
-Now that the project has been imported, open the project configuration.
+.. figure:: img/kdevelop_custombuild.png
+   :figclass: figure-w480
+   :align: center
 
-.. image:: img/kdevelop_openconfig.png
+- After the project has been imported, open the project configuration by right-clicking 
+  on it in the **Projects** panel and selecting **Open Configuration..** option.
 
-Add the following includes/imports:
+.. figure:: img/kdevelop_openconfig.png
+   :figclass: figure-w480
+   :align: center
 
-.. code-block:: none
+- Under **Language Support** open the **Includes/Imports** tab and add the following paths:
 
-    .  // a dot to indicate the root of the Godot project
-    core/
-    core/os/
-    core/math/
-    drivers/
-    platform/linuxbsd/  // make that platform/osx/ if you're using macOS
+  .. code-block:: none
 
-.. image:: img/kdevelop_addincludes.png
+     .  // A dot, to indicate the root of the Godot project
+     core/
+     core/os/
+     core/math/
+     drivers/
+     platform/<your_platform>/  // Replace <your_platform> with a folder 
+                                   corresponding to your current platform
 
-Apply the changes.
+.. figure:: img/kdevelop_addincludes.png
+   :figclass: figure-w480
+   :align: center
 
-Switch to the **Custom Build System** tab. Add a build configuration
-and keep the build directory blank. Enable build tools and add ``scons``
-as the executable then add ``platform=linuxbsd target=debug`` (``platform=osx``
-if you're on macOS) as the arguments.
+- Apply the changes.
+- Under **Custom Build System** add a new build configuration with the following settings:
 
-.. image:: img/kdevelop_buildconfig.png
+  +-----------------+------------------------------------------------------------------------------+
+  | Build Directory | *blank*                                                                      |
+  +-----------------+------------------------------------------------------------------------------+
+  | Enable          | **True**                                                                     |
+  +-----------------+------------------------------------------------------------------------------+
+  | Executable      | **scons**                                                                    |
+  +-----------------+------------------------------------------------------------------------------+
+  | Arguments       | See :ref:`doc_introduction_to_the_buildsystem` for a full list of arguments. |
+  +-----------------+------------------------------------------------------------------------------+
 
-Next, we need to tell KDevelop where to find the binary.
-From the **Run** menu, choose **Configure Launches**.
+.. figure:: img/kdevelop_buildconfig.png
+   :figclass: figure-w480
+   :align: center
 
-.. image:: img/kdevelop_configlaunches.png
+- Apply the changes and close the configuration window.
 
-Click **Add** if no launcher exists. Then add the path to your
-executable in the executable section. Your executable should be located
-in the ``bin/`` subdirectory and should be named something like
-``godot.linuxbsd.tools.64`` (the name could be different depending on your
-platform and build options).
+Debugging the project
+---------------------
 
-.. image:: img/kdevelop_configlaunches2.png
+- Select **Run > Configure Launches...** from the top menu.
+
+.. figure:: img/kdevelop_configlaunches.png
+   :figclass: figure-w480
+   :align: center
+
+- Click **Add** to create a new launch configuration.
+- Select **Executable** option and specify the path to your executable located in 
+  the ``<Godot root directory>/bin`` folder. The name depends on your build configuration,
+  e.g. ``godot.linuxbsd.tools.64`` for 64-bit LinuxBSD platform with ``tools`` enabled.
+
+.. figure:: img/kdevelop_configlaunches2.png
+   :figclass: figure-w480
+   :align: center
 
 If you run into any issues, ask for help in one of
 `Godot's community channels <https://godotengine.org/community>`__.

development/cpp/configuring_an_ide/qt_creator.rst

@@ -3,103 +3,109 @@
 Qt Creator
 ==========
 
-Qt Creator is a free, open source IDE for all desktop platforms.
+`Qt Creator <https://doc.qt.io/qtcreator/index.html>`_ is a free, open source IDE for all desktop platforms.
 
 Importing the project
 ---------------------
 
-- Choose **New Project > Import Project > Import Existing Project**.
+- From the Qt Creator's main screen select **New Project > Import Project > Import Existing Project**.
 
-.. image:: img/qtcreator-new-project.png
+.. figure:: img/qtcreator-new-project.png
+   :figclass: figure-w480
+   :align: center
 
-- Set the path to your Godot root directory and enter the project name.
+- Under **Location** select the Godot root folder.
 
-.. image:: img/qtcreator-set-project-path.png
+.. figure:: img/qtcreator-set-project-path.png
+   :figclass: figure-w480
+   :align: center
 
-- Here you can choose which folders and files will be visible to the project.
-  C/C++ files are added automatically. Potentially useful additions:
+- Next, you can choose which folders and files will be visible to the project.
+  While C/C++ files are added automatically, other extensions can be potentially useful:
   ``*.py`` for buildsystem files, ``*.java`` for Android platform development,
-  ``*.mm`` for macOS platform development. Click **Next**.
+  ``*.mm`` for macOS platform development.
 
-.. image:: img/qtcreator-apply-import-filter.png
+.. figure:: img/qtcreator-apply-import-filter.png
+   :figclass: figure-w480
+   :align: center
 
-- Click **Finish**.
-- Add a line containing ``.`` to ``project_name.includes`` to get working
-  code completion.
+.. note:: You can change this configuration later by right-clicking on your project
+          and selecting the **Edit Files...** option.
 
-.. image:: img/qtcreator-project-name-includes.png
+          .. figure:: img/qtcreator-edit-files-menu.png
+            :figclass: figure-w480
+            :align: center
 
-Build and run
---------------
 
-Build configuration:
+- Finish the import.
+- Open the ``project_name.includes`` file and add a line containing ``.`` to it
+  to correctly enable the code completion.
 
-- Click on **Projects** and open the **Build** tab.
-- Delete the predefined ``make`` build step.
-
-.. image:: img/qtcreator-projects-build.png
-
--  Click **Add Build Step > Custom Process Step**.
+.. figure:: img/qtcreator-project-name-includes.png
+   :figclass: figure-w480
+   :align: center
 
-.. image:: img/qtcreator-add-custom-process-step.png
-
-- Type ``scons`` in the **Command** field. If it fails with
-  ``Could not start process "scons"``, it can mean that ``scons`` is not in
-  your ``PATH`` environment variable. In this case, you'll have to specify the
-  full path to the SCons binary.
-- Fill the **Arguments** field with your compilation options
-  (e.g.: ``p=linuxbsd target=debug -j 4``).
+- From the left-side menu select **Projects** and open the **Build** tab.
+- Delete the predefined ``make`` build step.
 
-.. image:: img/qtcreator-set-scons-command.png
+.. figure:: img/qtcreator-projects-build.png
+   :figclass: figure-w480
+   :align: center
 
-Run configuration:
+- Click **Add Build Step > Custom Process Step** to add a new build step 
+  with the following settings:
 
-- Open the **Run** tab.
-- Point the **Executable** to your compiled Godot binary
-  (e.g: ``%{buildDir}/bin/godot.linuxbsd.opt.tools.64``).
-- If you want to run a specific project, point **Working directory** to the
-  project folder.
-- If you want to run the editor, add ``-e`` to the **Command line arguments**
-  field.
+  +-----------+------------------------------------------------------------------------------+
+  | Command   | **scons**                                                                    |
+  +-----------+------------------------------------------------------------------------------+
+  | Arguments | See :ref:`doc_introduction_to_the_buildsystem` for a full list of arguments. |
+  +-----------+------------------------------------------------------------------------------+
 
-.. image:: img/qtcreator-run-command.png
+.. figure:: img/qtcreator-set-scons-command.png
+   :figclass: figure-w480
+   :align: center
 
-Updating sources after pulling latest commits
----------------------------------------------
+.. note:: If the build fails with ``Could not start process "scons"``, it can mean that ``scons`` 
+          is not in your ``PATH`` environment variable. In this case, you'll have to specify the
+          full path to the SCons binary.
 
-As a developer, you usually want to frequently pull the latest commits from the
-upstream Git repository or a specific fork. However, this brings a problem with
-it: as the development continues, source files (and folders) are added or
-removed. These changes need to be reflected in your project files for Qt Creator
-too, so you continue to have a nice programming experience. A simple way to
-check is to right click at your root folder in the **Projects View** and click
-on **Edit files...**.
+Debugging the project
+---------------------
 
-.. image:: img/qtcreator-edit-files-menu.png
+- From the left-side menu select **Projects** and open the **Run** tab.
+- Under **Executable** specify the path to your executable located in 
+  the ``<Godot root directory>/bin`` folder. The name depends on your build configuration,
+  e.g. ``godot.linuxbsd.tools.64`` for 64-bit LinuxBSD platform with ``tools`` enabled.
+  You can use ``%{buildDir}`` to reference the project root, e.g: ``%{buildDir}/bin/godot.linuxbsd.opt.tools.64``.
+- If you want to run a specific project, specify its root folder under **Working directory**.
+- If you want to run the editor, add ``-e`` to the **Command line arguments** field.
 
-Now a new dialog should appear that is similar in functionality to the one in
-the third step of the *Importing the project* section above. Here, you can check
-whether you want to add/remove specific files and/or folders. You can choose by
-clicking with your mouse or just simply by clicking the **Apply Filter** button.
-Click on **OK** and you're ready to continue working.
+.. figure:: img/qtcreator-run-command.png
+   :figclass: figure-w480
+   :align: center
 
-.. image:: img/qtcreator-edit-files-dialog.png
+To learn more about command line arguments, refer to the
+:ref:`command line tutorial <doc_command_line_tutorial>`.
 
 Code style configuration
 ------------------------
 
 Developers must follow the project's :ref:`code style <doc_code_style_guidelines>`
-and the IDE should help them follow it. By default, Qt Creator does use spaces
+and the IDE should help them follow it. By default, Qt Creator uses spaces
 for indentation which doesn't match the Godot code style guidelines. You can
 change this behavior by changing the **Code Style** in **Options > C++**.
 
-.. image:: img/qtcreator-options-cpp.png
+.. figure:: img/qtcreator-options-cpp.png
+   :figclass: figure-w480
+   :align: center
 
 Click on **Edit** to change the current settings, then click on
 **Copy Built-in Code Style** button to set a new code style. Set a name for it
 (e.g. Godot) and change the Tab policy to be **Tabs Only**.
 
-.. image:: img/qtcreator-edit-codestyle.png
+.. figure:: img/qtcreator-edit-codestyle.png
+   :figclass: figure-w480
+   :align: center
 
 If you run into any issues, ask for help in one of
 `Godot's community channels <https://godotengine.org/community>`__.

development/cpp/configuring_an_ide/visual_studio.rst

@@ -3,62 +3,66 @@
 Visual Studio
 =============
 
-Visual Studio Community is a Windows-only IDE that's free for non-commercial use.
+`Visual Studio Community <https://visualstudio.microsoft.com>`__ is a Windows-only IDE 
+by `Microsoft <https://microsoft.com>`_ that's free for non-commercial use.
 It has many useful features, such as memory view, performance view, source
-control and more. You can get it
-`from Microsoft <https://visualstudio.microsoft.com/downloads/>`__.
+control and more.
 
-Setup
------
+Importing the project
+---------------------
 
-To start developing with Visual Studio, follow these steps:
+Visual Studio requires a solution file to work on a project. While Godot does not come
+with the solution file, it can be generated using SCons.
 
-- Open the Visual Studio Installer and install the C++ package:
+- Navigate to the Godot root folder and open a Command Prompt or PowerShell window.
+- Run ``scons platform=windows vsproj=yes`` to generate the solution.
+- You can now open the project by double-clicking on the ``godot.sln`` in the project root
+  or by using the **Open a project or solution** option inside of the Visual Studio.
+- Use the **Build** top menu to build the project.
 
-.. image:: img/vs_1_install_cpp_package.png
+.. warning:: Visual Studio must be configured with the C++ package. It can be selected
+             in the intaller:
 
-- Open a Command Prompt or PowerShell window, use ``cd`` to reach the Godot source
-  directory and run ``scons platform=windows vsproj=yes``.
+             .. figure:: img/vs_1_install_cpp_package.png
+                :align: center
 
-- Now open the Godot folder by clicking **Open a project or solution** and choose
-  ``godot.sln``.
-  - You can also double-click the ``godot.sln`` file in Explorer.
-
-You can now start developing with Visual Studio.
-
-Debugging
----------
+Debugging the project
+---------------------
 
 Visual Studio features a powerful debugger. This allows the user to examine Godot's
-source code, stop at specific points in the code, make changes, and view them on the run.
-
-.. note:: Debugging the Godot Engine inside the editor will require an extra setup step.
+source code, stop at specific points in the code, inspect the current execution context,
+and make live changes to the codebase.
 
-          Because opening Godot opens the Project Manager at first instead of the project
-          you're working on, the debugger will detach as soon as you open a project.
-          This means that the debugger will stop, even though Godot is still running in
-          another process.
+You can launch the project with the debugger attached using the **Debug > Start Debugging**
+option from the top menu. However, unless you want to debug the project manager specifically,
+you'd need to configure debugging options first. This is due to the fact that when the Godot 
+project manager opens a project, the initial process is terminated and the debugger gets detached.
 
-To overcome this, you need to edit the debugging command line arguments in VS. In your
-project, click **Project > Project Properties**:
+- To configure the launch options to use with the debugger use **Project > Properties**
+  from the top menu:
 
-.. image:: img/vs_2_project_properties.png
+.. figure:: img/vs_2_project_properties.png
+   :align: center
 
-Then add this to the command arguments:
+- Open the **Debugging** section and under **Command Arguments** add two new arguments: 
+  the ``-e`` flag opens the editor instead of the project manager, and the ``--path`` argument
+  tells the executable to open the specified project (must be provided as an *absolute* path 
+  to the project root, not the ``project.godot`` file).
 
-.. image:: img/vs_3_debug_command_line.png
-
-- The ``-e`` flag is for entering the editor directly (which skips the Project Manager).
-- The ``--path`` argument should be an *absolute* path to a project directory (not a
-  `project.godot` file).
+.. figure:: img/vs_3_debug_command_line.png
+   :align: center
 
 To learn more about command line arguments, refer to the
 :ref:`command line tutorial <doc_command_line_tutorial>`.
 
-To check that everything is working, put a breakpoint in ``main.cpp`` and press F5 to
+Even if you start the project without a debugger attached it can still be connected to the running
+process using **Debug > Attach to Process...** menu.
+
+To check that everything is working, put a breakpoint in ``main.cpp`` and press :kbd:`F5` to
 start debugging.
 
-.. image:: img/vs_4_debugging_main.png
+.. figure:: img/vs_4_debugging_main.png
+   :align: center
 
 If you run into any issues, ask for help in one of
 `Godot's community channels <https://godotengine.org/community>`__.

development/cpp/configuring_an_ide/visual_studio_code.rst

@@ -3,47 +3,104 @@
 Visual Studio Code
 ==================
 
-Visual Studio Code is a free cross-platform IDE (not to be confused with
-:ref:`doc_configuring_an_ide_vs`). You can get it
-`from Microsoft <https://code.visualstudio.com/>`__.
+`Visual Studio Code <https://code.visualstudio.com>`_ is a free cross-platform IDE 
+by `Microsoft <https://microsoft.com>`_ (not to be confused with :ref:`doc_configuring_an_ide_vs`).
 
+Importing the project
+---------------------
 
 - Make sure the C/C++ extension is installed. You can find instructions in
-  the `documentation <https://code.visualstudio.com/docs/languages/cpp>`_.
-- Open the cloned Godot folder in Visual Studio Code with
+  the `official documentation <https://code.visualstudio.com/docs/languages/cpp>`_.
+- From the Visual Studio Code's main screen open the Godot root folder with
   **File > Open Folder...**.
-
-In order to build the project, you need two configuration files:
-``launch.json`` and ``tasks.json``. To create them:
-
-- Open the **Debug** view by pressing :kbd:`Ctrl + Shift + D` and select the
-  cogwheel with an orange dot:
-
-.. image:: img/vscode_1_create_launch.json.png
-
-- Select **C++ (GDB/LLDB)** (it might be named differently on macOS or Windows).
-
-- Update ``launch.json`` to match:
-
-.. image:: img/vscode_2_launch.json.png
-
-If you're following this guide on macOS or Windows, you will have to adjust
-``godot.linuxbsd.tools.64`` accordingly.
-
-- Create a ``tasks.json`` file by starting the Debug process with :kbd:`F5`.
-  Visual Studio Code will show a dialog with a **Configure Task** button.
-  Choose it and select **Create tasks.json file from template**, then select **Others**.
-
-- Update ``tasks.json`` to match:
-
-.. image:: img/vscode_3_tasks.json.png
-
-If you're following this guide on macOS or Windows, you will have to adjust
-``platform=linuxbsd`` accordingly.
-
-- You can now start the Debug process again to test that everything works.
-- If the build phase fails, check the console for hints. On Linux, it's most
-  likely due to missing dependencies. Check :ref:`doc_compiling_for_linuxbsd`.
+- Press :kbd:`Ctrl + Shift + P` to open the command prompt window and enter *Configure Task*.
+
+.. figure:: img/vscode_configure_task.png
+   :align: center
+
+- Select the **Create tasks.json file from template** option.
+
+.. figure:: img/vscode_create_tasksjson.png
+   :align: center
+
+- Then select **Others**.
+
+.. figure:: img/vscode_create_tasksjson_others.png
+   :align: center
+
+- Within the ``tasks.json`` file find the ``"tasks"`` array and add a new section to it:
+
+.. code-block:: js
+
+  {
+    "label": "build",
+    "type": "shell",
+    "command": "scons",
+    "group": "build",
+    "args": [
+      "platform=linuxbsd", // Change to your current platform
+      "target=debug",
+      "-j4"
+    ],
+    "problemMatcher": "$msCompile"
+  }
+
+.. figure:: img/vscode_3_tasks.json.png
+   :figclass: figure-w480
+   :align: center
+
+   An example of a filled out ``tasks.json``.
+
+Arguments are can be different based on your own setup and needs. See 
+:ref:`doc_introduction_to_the_buildsystem` for a full list of arguments.
+
+Debugging the project
+---------------------
+
+To run and debug the project you need to create a new configuration in the ``launch.json`` file.
+
+- Press :kbd:`Ctrl + Shift + D` to open the Run panel.
+- If ``launch.json`` file is missing you will be prompted to create a new one.
+
+.. figure:: img/vscode_1_create_launch.json.png
+   :align: center
+
+- Select **C++ (GDB/LLDB)**. There may be another platform specific option here. If selected,
+  adjust the configuration example provided accordingly.
+- Within the ``launch.json`` file find the ``"configurations"`` array and add a new section to it:
+
+.. code-block:: js
+
+  {
+    "name": "Launch",
+    "type": "cppdbg",
+    "request": "launch",
+    "program": "${workspaceFolder}/bin/godot.linuxbsd.tools.64",
+                                      // Change to your current platform
+    "args": [ "-e" ],
+    "stopAtEntry": false,
+    "cwd": "${workspaceFolder}",
+    "environment": [],
+    "externalConsole": true,
+    "MIMode": "gdb",
+    "setupCommands": [
+      {
+        "description": "Enable pretty-printing for gdb",
+        "text": "-enable-pretty-printing",
+        "ignoreFailures": true
+      }
+    ],
+    "preLaunchTask": "build"
+  }
+
+.. figure:: img/vscode_2_launch.json.png
+   :figclass: figure-w480
+   :align: center
+
+   An example of a filled out ``launch.json``.
+
+The name under ``program`` depends on your build configuration,
+e.g. ``godot.linuxbsd.tools.64`` for 64-bit LinuxBSD platform with ``tools`` enabled.
 
 If you run into any issues, ask for help in one of
 `Godot's community channels <https://godotengine.org/community>`__.

development/cpp/configuring_an_ide/xcode.rst

@@ -3,93 +3,108 @@
 Xcode
 =====
 
-Xcode is a free macOS-only IDE. You can download it from the Mac App Store.
+`Xcode <https://developer.apple.com/xcode>`_ is a free macOS-only IDE. You can 
+download it from the Mac App Store.
 
-Project setup
--------------
+Importing the project
+---------------------
 
-- Create an Xcode external build project anywhere.
+- From Xcode's main screen create a new project using the **Other > External Build System** template.
 
-.. image:: img/xcode_1_create_external_build_project.png
+.. figure:: img/xcode_1_create_external_build_project.png
+   :figclass: figure-w480
+   :align: center
 
-Go to the build target's **Info** tab, then:
+- Open your build targets from the **Targets** section and select the **Info** tab.
+- Fill out the form with the following settings:
 
-- Set **Build Tool** to the full path to SCons.
-- Set **Arguments** to something like
-  ``platform=osx tools=yes bits=64 target=debug``.
-- Set **Directory** to the path to Godot's source folder.
-- You may uncheck **Pass build settings in environment**.
+  +------------+------------------------------------------------------------------------------+
+  | Build Tool | A full path to the **scons** executable, e.g. **/usr/local/bin/scons**       |
+  +------------+------------------------------------------------------------------------------+
+  | Arguments  | See :ref:`doc_introduction_to_the_buildsystem` for a full list of arguments. |
+  +------------+------------------------------------------------------------------------------+
+  | Directory  | A full path to the Godot root folder                                         |
+  +------------+------------------------------------------------------------------------------+
 
-.. image:: img/xcode_2_configure_scons.png
+.. figure:: img/xcode_2_configure_scons.png
+   :figclass: figure-w480
+   :align: center
 
-Add a Command Line Tool target which will be used for indexing the project:
+- Add a Command Line Tool target which will be used for indexing the project by
+  choosing **File > New > Target...**.
 
-- In Xcode's menu, choose **File > New > Target...** and add a new Xcode
-  command line tool target.
+.. figure:: img/xcode_3_add_new_target.png
+   :figclass: figure-w480
+   :align: center
 
-.. image:: img/xcode_3_add_new_target.png
+- Select **OS X > Application > Command Line Tool**.
 
-.. image:: img/xcode_4_select_command_line_target.png
+.. figure:: img/xcode_4_select_command_line_target.png
+   :figclass: figure-w480
+   :align: center
 
-- Name it something so you know not to compile with this target (e.g. ``GodotXcodeIndex``).
-- Goto the newly created target's **Build Settings** tab and look for **Header Search Paths**.
-- Set **Header Search Paths** to the absolute path to Godot's source folder.
-- Make it recursive by adding two asterisks (``**``) to the end of the path,
-  e.g. ``/Users/me/repos/godot-source/**``.
+.. note:: Name it something so you know not to compile with this target (e.g. ``GodotXcodeIndex``).
 
-Add the Godot source to the project:
+- For this target open the **Build Settings** tab and look for **Header Search Paths**.
+- Set **Header Search Paths** to the absolute path to the Godot root folder. You need to
+  include subdirectories as well. To achieve that, add two two asterisks (``**``) to the 
+  end of the path, e.g. ``/Users/me/repos/godot-source/**``.
 
-- Drag and drop Godot source into the project file browser.
+- Add the Godot source to the project by dragging and dropping it into the project file browser.
 - Uncheck **Create external build system project**.
 
-.. image:: img/xcode_5_after_add_godot_source_to_project.png
+.. figure:: img/xcode_5_after_add_godot_source_to_project.png
+   :figclass: figure-w480
+   :align: center
 
-- Click **Next**.
-- Select **Create groups**.
+- Next select **Create groups** for the **Added folders** option and check *only* 
+  your command line indexing target in the **Add to targets** section.
 
-.. image:: img/xcode_6_after_add_godot_source_to_project_2.png
+.. figure:: img/xcode_6_after_add_godot_source_to_project_2.png
+   :figclass: figure-w480
+   :align: center
 
-- Check *only* your command line indexing target in the
-  **Add to targets** section.
-- Click finish. Xcode will now index the files. This may take a few minutes.
+- Xcode will now index the files. This may take a few minutes.
 - Once Xcode is done indexing, you should have jump-to-definition,
   autocompletion, and full syntax highlighting.
 
-Scheme setup
-------------
+Debugging the project
+---------------------
 
-To enable debugging support, edit the external build target's build scheme:
+To enable debugging support you need to edit the external build target's build and run schemes.
 
 - Open the scheme editor of the external build target.
-- Expand the **Build** menu.
-- Goto **Post Actions**.
-- Add a new script run action, select your project in **Provide build settings from**
-  as this allows you to use the``${PROJECT_DIR}`` variable.
+- Locate the **Build > Post Actions** section.
+- Add a new script run action
+- Under **Provide build settings from** select your project. This allows to reference 
+  the project directory within the script.
+- Create a script that will give the binary a name that Xcode can recognize, e.g.:
 
-.. image:: img/xcode_7_setup_build_post_action.png
+.. code-block:: shell
 
-- Write a script that gives the binary a name that Xcode will recognize, such as:
-  ``ln -f ${PROJECT_DIR}/godot/bin/godot.osx.tools.64 ${PROJECT_DIR}/godot/bin/godot``
-- Build the external build target.
+  ln -f ${PROJECT_DIR}/godot/bin/godot.osx.tools.64 ${PROJECT_DIR}/godot/bin/godot
 
-Edit the external build target's Run scheme:
+.. figure:: img/xcode_7_setup_build_post_action.png
+   :figclass: figure-w480
+   :align: center
 
-- Open the scheme editor again.
-- Click **Run**.
+- Build the external build target.
 
-.. image:: img/xcode_8_setup_run_scheme.png
+- Open the scheme editor again and select **Run**.
 
-- Set the **Executable** to the file you linked in your post-build action script.
-- Check **Debug executable** if it isn't checked already.
-- You can go to **Arguments** tab and specify the full path to a
-  ``project.godot`` file to debug the editor instead of the project manager.
-  Alternatively, use ``--path`` to point to a project *folder* which will be
-  run directly (instead of opening the editor).
+.. figure:: img/xcode_8_setup_run_scheme.png
+   :figclass: figure-w480
+   :align: center
 
-Test the Run scheme:
-
-- Set a breakpoint in ``platform/osx/godot_main_osx.mm``.
-- If all goes well, it should break at the specified breakpoint.
+- Set the **Executable** to the file you linked in your post-build action script.
+- Check **Debug executable**.
+- You can add two arguments on the **Arguments** tab:
+  the ``-e`` flag opens the editor instead of the project manager, and the ``--path`` argument
+  tells the executable to open the specified project (must be provided as an *absolute* path 
+  to the project root, not the ``project.godot`` file).
+
+To check that everything is working, put a breakpoint in ``platform/osx/godot_main_osx.mm`` and
+run the project.
 
 If you run into any issues, ask for help in one of
 `Godot's community channels <https://godotengine.org/community>`__.