Merge branch 'master' into 3.2

.mailmap

@@ -0,0 +1,30 @@
+Andreas Haas <[email protected]>
+Andrew Conrad <[email protected]>
+Andrii Doroshenko <[email protected]>
+puchik <[email protected]> <[email protected]>
+Chris Bradfield <[email protected]> <[email protected]>
+clayjohn <[email protected]>
+clayjohn <[email protected]> <[email protected]>
+corrigentia <[email protected]> <[email protected]>
+Frido <[email protected]>
+Frido <[email protected]> <[email protected]>
+Hugo Locurcio <[email protected]> <[email protected]>
+Hugo Locurcio <[email protected]> <[email protected]>
+Ignacio Etcheverry <[email protected]> <[email protected]>
+Julian Murgia <[email protected]>
+Kelly Thomas <[email protected]>
+Leon Krause <[email protected]>
+Leon Krause <[email protected]> <[email protected]>
+Max Hilbrunner <[email protected]>
+Max Hilbrunner <[email protected]> <[email protected]>
+Michael Alexsander <[email protected]>
+Nathan Lovato <[email protected]>
+Paul Joannon <[email protected]> <[email protected]>
+Rémi Verschelde <[email protected]> <[email protected]>
+skyace65 <[email protected]>
+skyace65 <[email protected]> <[email protected]>
+TwistedTwigleg <[email protected]> <[email protected]>
+Will Nations <[email protected]>
+Yuri Roubinsky <[email protected]>
+Yuri Sizov <[email protected]> <[email protected]>
+ZX-WT <[email protected]> <[email protected]>

AUTHORS.md

@@ -0,0 +1,53 @@
+# Godot Engine documentation authors
+
+Godot Engine is developed by a community of voluntary contributors who
+contribute on all areas, including writing and maintaining the documentation.
+
+It is impossible to list them all; nevertheless, this file aims at listing
+the writers who contributed significant patches to this CC-BY licensed
+documentation on the `godot-docs` repository.
+
+GitHub usernames are indicated in parentheses, or as sole entry when no other
+name is available.
+
+## Main contributors
+
+(in alphabetical order, with over 10 commits excluding merges)
+
+Aaron Franke (aaronfranke)
+Andrew Conrad (her001)
+Andrii Doroshenko (Xrayez)
+Arman (puchik)
+Bastiaan Olij (BastiaanOlij)
+bitbutter
+Camille Mohr-Daurat (pouleyKetchoupp)
+Chris Bradfield (cbscribe)
+Clay John (clayjohn)
+corrigentia
+Fabio Alessandrelli (Faless)
+FeralBytes
+Frido (mega-bit)
+George Marques (vnen)
+Gerrit Großkopf (Grosskopf)
+Griatch
+Haoyu Qiu (timothyqiu)
+Hugo Locurcio (Calinou)
+Ignacio Roldán Etcheverry (neikeq)
+Jérôme Gully (Nutriz)
+Juan Linietsky (reduz)
+Julian Murgia (StraToN)
+Kelly Thomas (KellyThomas)
+Leon Krause (leonkrause)
+Matthew (skyace65)
+Max Hilbrunner (mhilbrunner)
+Michael Alexsander (YeldhamDev)
+Nathan Lovato (NathanLovato)
+Paul Joannon (paulloz)
+Poommetee Ketson (Naryosha)
+Rémi Verschelde (akien-mga)
+Tomasz Chabora (KoBeWi)
+TwistedTwigleg
+Will Nations (willnationsdev)
+Yuri Roubinsky (Chaosus)
+Yuri Sizov (pycbouh)
+ZX-WT

README.md

@@ -69,7 +69,7 @@ Building the documentation requires at least 8 GB of RAM to be done without swap
 # On Linux/macOS
 make html SPHINXOPTS=-j2
 
-# On Windows
+# On Windows
 set SPHINXOPTS=-j2 && make html
 ```
 

_static/css/custom.css

@@ -205,6 +205,13 @@ legend,
     font-weight: 500;
 }
 
+.rst-content div.figure p.caption {
+    /* Tweak caption styling to be closer to typical captions */
+    text-align: center;
+    margin-top: 8px;
+    opacity: 0.75;
+}
+
 p,
 article ul,
 article ol,
@@ -334,7 +341,7 @@ footer,
 /* Sphinx Search extension */
 /* .wy-body-for-nav is used for higher rule specificity */
 
-/* search popup body */
+/* Search popup body */
 .wy-body-for-nav .search__outer {
     background-color: var(--content-background-color);
     border: 2px solid var(--content-background-color);
@@ -357,7 +364,7 @@ footer,
     background-color: var(--hr-color);
 }
 
-/* search input */
+/* Search input */
 .wy-body-for-nav .search__outer__input {
     background-color: var(--search-input-background-color);
     background-image: none;
@@ -375,11 +382,11 @@ footer,
     display: none;
 }
 
-/* search item */
+/* Search results item */
 .wy-body-for-nav .search__result__single {
     border-bottom-color: var(--hr-color);
 }
-/* search item title */
+/* Search item title */
 .wy-body-for-nav .search__result__title {
     color: var(--link-color);
     border-bottom: none;
@@ -387,7 +394,7 @@ footer,
     font-weight: 400;
 }
 
-/* search item section */
+/* Search item section */
 .wy-body-for-nav .outer_div_page_results:hover,
 .wy-body-for-nav .search__result__box .active {
     background-color: var(--search-active-color);
@@ -401,7 +408,7 @@ footer,
     color: var(--footer-color);
 }
 
-/* search item matching substring */
+/* Search item matching substring */
 .wy-body-for-nav .search__outer .search__result__title span,
 .wy-body-for-nav .search__outer .search__result__content span {
     color: var(--search-match-color);
@@ -413,7 +420,13 @@ footer,
     border-bottom-color: var(--body-color);
 }
 
-/* search credits */
+/* Search empty results */
+/* The original styles are inlined, see https://github.com/readthedocs/readthedocs-sphinx-search/issues/48 */
+.wy-body-for-nav .search__result__box {
+    color: var(--body-color) !important;
+}
+
+/* Search footer & credits */
 .wy-body-for-nav .rtd__search__credits {
     background-color: var(--search-credits-background-color);
     border-color: var(--search-credits-background-color);

_templates/layout.html

@@ -7,7 +7,7 @@
   <link rel="alternate" hreflang="{{ alternate_lang_href }}" href="{{ godot_docs_basepath }}{{ alternate_lang }}/{{ godot_canonical_version }}/{{ pagename }}{{ godot_docs_suffix }}" />
   {% endfor -%}
   <link rel="alternate" hreflang="x-default" href="{{ godot_docs_basepath }}{{ godot_default_lang }}/{{ godot_canonical_version }}/{{ pagename }}{{ godot_docs_suffix }}" />
-  
+
   <link rel="canonical" href="{{ godot_docs_basepath }}{{ lang_attr }}/{{ godot_canonical_version }}/{{ pagename }}{{ godot_docs_suffix }}" />
   {% endif -%}
   {{ super() }}

about/docs_changelog.rst

@@ -3,9 +3,10 @@
 Documentation changelog
 =======================
 
-The documentation is continually being improved. The release of version 3.1
+The documentation is continually being improved. The release of version 3.2
 includes many new tutorials, many fixes and updates for old tutorials, and many updates
-to the class reference. Below is a list of new tutorials added since version 3.0.
+to the :ref:`class reference <toc-class-ref>`. Below is a list of new tutorials
+added since version 3.1.
 
 .. note:: This document only contains new tutorials so not all changes are reflected,
           many tutorials have been substantially updated but are not reflected in this document.
@@ -26,6 +27,7 @@ Project workflow
 Audio
 ^^^^^
 
+- :ref:`doc_recording_with_microphone`
 - :ref:`doc_sync_with_audio`
 
 Math
@@ -47,12 +49,12 @@ Internationalization
 Shading
 ^^^^^^^
 
-Your First Shader Series:
-
-- :ref:`doc_what_are_shaders`
-- :ref:`doc_your_first_canvasitem_shader`
-- :ref:`doc_your_first_spatial_shader`
-- :ref:`doc_your_second_spatial_shader`
+- Your First Shader Series:
+    - :ref:`doc_what_are_shaders`
+    - :ref:`doc_your_first_canvasitem_shader`
+    - :ref:`doc_your_first_spatial_shader`
+    - :ref:`doc_your_second_spatial_shader`
+- :ref:`doc_visual_shaders`
 
 Networking
 ^^^^^^^^^^

community/contributing/best_practices_for_engine_contributors.rst

@@ -23,7 +23,7 @@ Best Practices
 #1: The problem always comes first
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Many contributors are extremely creative and just enjoy the process of designing abstract data structures, creating nice user interfaces,or simply love programming. Whatever the case may be, they come up with cool ideas, which may not be actually solving any actual problems.
+Many contributors are extremely creative and just enjoy the process of designing abstract data structures, creating nice user interfaces, or simply love programming. Whatever the case may be, they come up with cool ideas, which may not be actually solving any actual problems.
 
 .. image:: img/best_practices1.png
 
@@ -38,7 +38,7 @@ This is a variation of the previous practice. I believe most developers agree th
 
 The answer to this question is that the problem needs to *exist*. It must not be speculation or a belief. The user must be using the software as intended to create something they *need*. In this process, the user may stumble into a problem that requires a solution in order to continue, or in order to achieve greater productivity. In this case, *a solution is needed*.
 
-Believing that problems may arise in the future and that the software needs to be ready to solve them by the time they appear is called *"Future proofing"* and its characterized by lines of thought such as: 
+Believing that problems may arise in the future and that the software needs to be ready to solve them by the time they appear is called *"Future proofing"* and its characterized by lines of thought such as:
 
 - I think it would be useful for users to...
 - I think users will eventually need to...
@@ -72,16 +72,16 @@ Because of this, user proposed solutions don't always contemplate other use case
 
 .. image:: img/best_practices4.png
 
-For developers, the perspective is different. They may find the user's problem too unique to justify a solution (instead of a user workaround), or maybe they will suggest a partial (usually simpler or lower level) solution that applies to a wider range of known problems, and leave the rest of the solution up to the user. 
+For developers, the perspective is different. They may find the user's problem too unique to justify a solution (instead of a user workaround), or maybe they will suggest a partial (usually simpler or lower level) solution that applies to a wider range of known problems, and leave the rest of the solution up to the user.
 
-In any case, before attempting a contribution, it is important to discuss the actual problems with the other developers or contributors, so a better agreement on implementation can be reached. 
+In any case, before attempting a contribution, it is important to discuss the actual problems with the other developers or contributors, so a better agreement on implementation can be reached.
 
 The only exception, in this case, is when an area of code has a clear owner (agreed by the other contributors), who talks to users directly and has the most knowledge to implement a solution directly.
 
 #5: To each problem, its own solution
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For programmers, it is always a most enjoyable challenge to find the most optimal solutions to problems. Things, however, may go overboard sometimes and programmers will try to come up with solutions that solve as many problems as possible. 
+For programmers, it is always a most enjoyable challenge to find the most optimal solutions to problems. Things, however, may go overboard sometimes and programmers will try to come up with solutions that solve as many problems as possible.
 
 The situation will often take a turn for the worse when, in order to make this solution appear even more fantastic and flexible, the pure speculation-based problems (as described in #2) also make their appearance on stage.
 
@@ -98,7 +98,7 @@ Big and flexible solutions also have an additional drawback which is that, over
 
 This is a continuation of the previous point, which further explains why this way of thinking and designing software is preferred.
 
-As mentioned before (in point #2), it is very difficult for us (as human beings who design software) to actually understand all future user needs. Trying to write very flexible structures that cater to many use cases at once is often a mistake. 
+As mentioned before (in point #2), it is very difficult for us (as human beings who design software) to actually understand all future user needs. Trying to write very flexible structures that cater to many use cases at once is often a mistake.
 
 We may come up with something we believe is brilliant, but when it's actually used, we will find that users will never even use half of it, or that they will require features that don't quite accommodate our original design, forcing us to either throw it away or make it even more complex.
 
@@ -115,7 +115,7 @@ In real-life scenarios, these use cases will be at most rare and uncommon anyway
 
 When looking for a solution to a problem, be it implementing a new feature or fixing a bug, sometimes the easiest path is to add data or a new function in the core layers of code.
 
-The main problem here is, adding something to the core layers that will only be used from a single location far away will not only make the code more difficult to follow (split in two), but also make the core API larger, more complex, more difficult to understand in general. 
+The main problem here is, adding something to the core layers that will only be used from a single location far away will not only make the code more difficult to follow (split in two), but also make the core API larger, more complex, more difficult to understand in general.
 
 This is bad, because readability and cleanness of core APIs is always of extreme importance given how much code relies on it, and because it's key for new contributors as a starting point to learning the codebase.
 

community/contributing/pr_workflow.rst

@@ -60,9 +60,11 @@ The branches on the Git repository are organized as follows:
    As a rule of thumb, the last stable branch is maintained until the next
    major version (e.g. the ``3.0`` branch was maintained until the release of
    Godot 3.1).
-   If you want to make PRs against a maintained stable branch, you will have
-   to check if your changes are also relevant for the ``master`` branch.
--  There might be feature branches at time, usually meant to be merged into
+   If you want to make PRs against a maintained stable branch, please check
+   first if your changes are also relevant for the ``master`` branch, and if so
+   make the PR for the ``master`` branch in priority. Release managers can then
+   cherry-pick the fix to a stable branch if relevant.
+-  There might occasionally be feature branches, usually meant to be merged into
    the ``master`` branch at some time.
 
 Forking and cloning
@@ -113,9 +115,9 @@ We will start by setting up a reference to the original repository that we forke
     $ git fetch upstream
 
 This will create a reference named ``upstream`` pointing to the original
-godotengine/godot repository. This will be useful when you want to pull new
+``godotengine/godot`` repository. This will be useful when you want to pull new
 commits from its ``master`` branch to update your fork. You have another
-``remote`` reference named ``origin``, which points to your fork.
+remote reference named ``origin``, which points to your fork (``USERNAME/godot``).
 
 You only need to do the above steps once, as long as you keep that local
 ``godot`` folder (which you can move around if you want, the relevant
@@ -132,7 +134,7 @@ metadata is hidden in its ``.git`` subfolder).
           when lost, so we will give you the basic commands to know when
           working in Git.
 
-In the following, we will assume that you want to implement a feature in
+In the following, we will assume as an example that you want to implement a feature in
 Godot's project manager, which is coded in the ``editor/project_manager.cpp``
 file.
 
@@ -174,6 +176,14 @@ command:
     * better-project-manager
       master
 
+Be sure to always go back to the ``master`` branch before creating a new branch,
+as your current branch will be used as the base for the new one. Alternatively,
+you can specify a custom base branch after the new branch's name:
+
+::
+
+    $ git checkout -b my-new-feature master
+
 Updating your branch
 --------------------
 
@@ -187,42 +197,55 @@ To ensure there won't be conflicts between the feature you develop and the
 current upstream ``master`` branch, you will have to update your branch by
 *pulling* the upstream branch.
 
-::
-
-    $ git pull upstream master
-
-However, if you had local commits, this method will create a so-called "merge
-commit", and you will soon hear from fellow contributors that those are not
-wanted in PRs. To update the branch without creating a merge commit,
-you will have to use the ``--rebase`` option, so that your local commits are
-replayed on top of the updated upstream ``master`` branch. It will effectively
-modify the Git history of your branch, but that is for the greater good.
-
-Therefore, the command that you should (almost) always use is:
-
 ::
 
     $ git pull --rebase upstream master
 
-
-If you have already pushed the merge commit without using ``rebase``, or
-have made any other changes that have resulted in undesired history, you may
-use a hard reset to revert to a specific commit and try again:
-
-::
-
-    $ git reset --hard [The ID of the last desired commit]
-
-Once you have done this, you may run ``--rebase`` to merge master correctly.
-
-If you have already pushed the wrong commits to your remote branch,
-you will have to force push by using ``git push --force``.
-
-.. warning:: ``git reset --hard`` can be a dangerous operation, especially
-            if you have untracked or uncommitted changes. However, if
-            you have committed changes that you reset using ``git reset --hard``,
-            you may still be able to recover them by resetting to a commit ID
-            found with the ``git reflog`` command.
+The ``--rebase`` argument will ensure that any local changes that you committed
+will be re-applied *on top* of the pulled branch, which is usually what we want
+in our PR workflow. This way, when you open a pull request, your own commits will
+be the only difference with the upstream ``master`` branch.
+
+While rebasing, conflicts may arise if your commits modified code that has been
+changed in the upstream branch in the meantime. If that happens, Git will stop at
+the conflicting commit and will ask you to resolve the conflicts. You can do so
+with any text editor, then stage the changes (more on that later), and proceed with
+``git rebase --continue``. Repeat the operation if later commits have conflicts too,
+until the rebase operation completes.
+
+If you're unsure about what is going on during a rebase and you panic (no worry,
+we all do the first few times), you can abort the rebase with ``git rebase --abort``.
+You will then be back to the original state of your branch before calling
+``git pull --rebase``.
+
+.. note:: If you omit the ``--rebase`` argument, you will instead create a merge
+          commit which tells Git what to make of the two distinct branches. If any
+          conflicts arise, they would be resolved all at once via this merge commit.
+
+          While this is a valid workflow and the default behavior of ``git pull``,
+          merge commits within PRs are frowned upon in our PR workflow. We only use
+          them when merging PRs into the upstream branch.
+
+          The philosophy is that a PR should represent the final stage of the changes
+          made to the codebase, and we are not interested in mistakes and fixes that
+          would have been done in intermediate stages before merging.
+          Git gives us great tools to "rewrite the history" and make it as if we got
+          things right the first time, and we're happy to use it to ensure that
+          changes are easy to review and understand long after they have been merged.
+
+If you have already created a merge commit without using ``rebase``, or
+have made any other changes that have resulted in undesired history, the best option
+is to use an *interactive rebase* on the upstream branch. See the :ref:`dedicated
+section <doc_pr_workflow_rebase>` for instructions.
+
+.. tip:: If at any time you want to *reset* a local branch to a given commit or branch,
+         you can do so with ``git reset --hard <commit ID>`` or
+         ``git reset --hard <remote>/<branch>`` (e.g. ``git reset --hard upstream/master``).
+
+         Be warned that this will remove any changes that you might have committed in
+         this branch. If you ever lose commits by mistake, use the ``git reflog`` command
+         to find the commit ID of the previous state that you would like to restore, and
+         use it as argument of ``git reset --hard`` to go back to that state.
 
 Making changes
 --------------
@@ -256,6 +279,9 @@ before staging it, while it is staged, and after it has been committed.
   variable or the ``core.editor`` setting in your Git configuration) to let you
   write a commit log. You can use ``git commit -m "Cool commit log"`` to
   write the log directly.
+- ``git commit --amend`` lets you amend the last commit with your currently
+  staged changes (added with ``git add``). This is the best option if you
+  want to fix a mistake in the last commit (bug, typo, style issue, etc.).
 - ``git log`` will show you the last commits of your current branch. If you
   did local commits, they should be shown at the top.
 - ``git show`` will show you the changes of the last commit. You can also
@@ -330,12 +356,12 @@ Issuing a pull request
 When you load your fork's branch on GitHub, you should see a line saying
 *"This branch is 2 commits ahead of godotengine:master."* (and potentially some
 commits behind, if your ``master`` branch was out of sync with the upstream
-``master`` branch.
+``master`` branch).
 
 .. image:: img/github_fork_make_pr.png
 
 On that line, there is a "Pull request" link. Clicking it will open a form
-that will let you issue a pull request on the godotengine/godot upstream
+that will let you issue a pull request on the ``godotengine/godot`` upstream
 repository. It should show you your two commits, and state "Able to merge".
 If not (e.g. it has way more commits, or says there are merge conflicts),
 don't create the PR, something went wrong. Go to IRC and ask for support :)
@@ -367,37 +393,84 @@ branch, push it to your fork, and the PR will be updated automatically:
     $ git commit -m "Fix a typo in the banner's title"
     $ git push origin better-project-manager
 
-That should do the trick, but...
+However, be aware that in our PR workflow, we favor commits that bring the
+codebase from one functional state to another functional state, without having
+intermediate commits fixing up bugs in your own code or style issues. Most of
+the time, we will prefer a single commit in a given PR (unless there's a good
+reason to keep the changes separate), so instead of authoring a new commit,
+considering using ``git commit --amend`` to amend the previous commit with your
+fixes. The above example would then become:
+
+::
+
+    # Check out your branch again if you had changed in the meantime
+    $ git checkout better-project-manager
+
+    # Fix a mistake
+    $ nano editor/project_manager.cpp
+    $ git add editor/project_manager.cpp
+    # --amend will change the previous commit, so you will have the opportunity
+    # to edit its commit message if relevant.
+    $ git commit --amend
+    # As we modified the last commit, it no longer matches the one from your
+    # remote branch, so we need to force push to overwrite that branch.
+    $ git push --force origin better-project-manager
+
+.. Kept for compatibility with the previous title, linked in many PRs.
 
-Mastering the PR workflow: the rebase
--------------------------------------
+.. _mastering-the-pr-workflow-the-rebase:
 
-On the situation outlined above, your fellow contributors who are particularly
-pedantic regarding the Git history might ask your to *rebase* your branch to
-*squash* or *meld* the last two commits together (i.e. the two related to the
-project manager), as the second commit basically fixes an issue in the first one.
+.. _doc_pr_workflow_rebase:
 
-Once the PR is merged, it is not relevant for a changelog reader that the PR
-author made mistakes; instead, we want to keep only commits that bring from
-one working state to another working state.
+The interactive rebase
+----------------------
+
+If you didn't follow the above steps closely to *amend* changes into a commit
+instead of creating fixup commits, or if you authored your changes without being
+aware of our workflow and Git usage tips, reviewers might request of your to
+*rebase* your branch to *squash* some or all of the commits into one.
+
+Indeed, if some commits have been made following reviews to fix bugs, typos, etc.
+in the original commit, they are not relevant to a future changelog reader who
+would want to know what happened in the Godot codebase, or when and how a given
+file was last modified.
 
-To squash those two commits together, we will have to *rewrite history*.
-Right, we have that power. You may read that it's a bad practice, and it's
-true when it comes to branches of the upstream repo. But in your fork, you
+To squash those extraneous commits into the main one, we will have to *rewrite
+history*. Right, we have that power. You may read that it's a bad practice, and
+it's true when it comes to branches of the upstream repo. But in your fork, you
 can do whatever you want, and everything is allowed to get neat PRs :)
 
 We will use the *interactive rebase* ``git rebase -i`` to do this. This
-command takes a commit hash as argument, and will let you modify all commits
-between that commit hash and the last one of the branch, the so-called
-*HEAD*. In our example, we want to act on the last two commits, so we will
-do:
+command takes a commit ID or a branch name as argument, and will let you modify
+all commits between that commit/branch and the last one in your working branch,
+the so-called ``HEAD``.
+
+While you can give any commit ID to ``git rebase -i`` and review everything in
+between, the most common and convenient workflow involves rebasing on the
+*upstream ``master`` branch*, which you can do with:
 
 ::
 
-    # The HEAD~X syntax means X commits before HEAD
-    $ git rebase -i HEAD~2
+    $ git rebase -i upstream/master
 
-This will open a text editor with:
+.. note:: Referencing branches in Git is a bit tricky due to the distinction
+          between remote and local branches. Here, ``upstream/master`` (with a
+          `/`) is a local branch which has been pulled from the ``upstream``
+          remote's ``master`` branch.
+
+          Interactive rebases can only be done on local branches, so the `/`
+          is important here. As the upstream remote changes frequently, your
+          local ``upstream/master`` branch may become outdated, so you can
+          update it with ``git fetch upstream master``. Contrarily to
+          ``git pull --rebase upstream master`` which would update your
+          currently checked out branch, ``fetch`` will only update the
+          ``upstream/master`` reference (which is distinct from your local
+          ``master`` branch... yes it's confusing, but you'll become familiar
+          with this little by little).
+
+This will open a text editor (``vi`` by default, see
+`Git docs <https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#_core_editor>__`
+to configure your favorite one) with something which may look like this:
 
 .. code-block:: text
 
@@ -422,12 +495,6 @@ will be melded into the first one, and ``git log`` and ``git show`` should
 now confirm that you have only one commit with the changes from both previous
 commits.
 
-.. note:: You could have avoided this rebase by using ``git commit --amend``
-          when fixing the typo. This command will write the staged changes
-          directly into the *last* commit (``HEAD``), instead of creating a new
-          commit like we did in this example. So it is equivalent to what we
-          did with a new commit and then a rebase to mark it as "fixup".
-
 But! You rewrote the history, and now your local and remote branches have
 diverged. Indeed, commit 1b4aad7 in the above example will have changed, and
 therefore got a new commit hash. If you try to push to your remote branch, it
@@ -476,3 +543,6 @@ Next, to delete the remote branch on GitHub use this command:
 ::
 
     $ git push origin -d better-project-manager
+
+You can also delete the remote branch from the GitHub PR itself, a button should appear once
+it has been merged or closed.

community/contributing/updating_the_class_reference.rst

@@ -5,6 +5,8 @@ Contribute to the Class Reference
 
 .. highlight:: shell
 
+.. note:: This guide also is available as a `video tutorial on YouTube <https://www.youtube.com/watch?v=5jeHXxeX-JY>`_.
+
 Godot ships with many nodes and singletons to help you develop your games. Each is a class, documented in the :ref:`class reference <toc-class-ref>`.
 This reference is essential for anyone learning the engine: it is available both online and in the engine.
 
@@ -14,8 +16,10 @@ The developers can't write the entire reference on their own. Godot needs you, a
 **Important:** If you are planning to make larger changes or a more substantial contribution, it is usually a good idea
 to create an issue (or a comment in an existing one) to let others know so they don't start working on the same thing too.
 
-.. note:: This guide is available as a `video tutorial on YouTube <https://www.youtube.com/watch?v=5jeHXxeX-JY>`_.
+.. seealso::
 
+    Not sure where to start contributing? Take a look at the current class reference
+    completion status `here <https://godotengine.github.io/doc-status/>`__.
 
 How to contribute
 -----------------
@@ -41,7 +45,7 @@ If you're new to git and GitHub, this guide will help you get started. You'll le
 - Keep your fork up to date with other contributors
 - Create a pull request so your improvements end in the official docs
 
-.. note:: If you're new to git, the version-control system Godot uses, go through `GitHub's interactive guide <https://try.github.io/levels/1/challenges/1>`_. You'll learn some essential vocabulary and get a sense for the tool.
+.. note:: If you're new to Git, the version control system Godot uses, go through `GitHub's interactive guide <https://try.github.io/levels/1/challenges/1>`_. You'll learn some essential vocabulary and get a sense for the tool.
 
 Fork Godot
 ~~~~~~~~~~
@@ -126,7 +130,7 @@ When classes are modified in the source code, the documentation template might b
 
     ./bin/godot.x11.tools.64 --doctool .
 
-The xml files in doc/classes should then be up-to-date with current Godot Engine features. You can then check what changed using the ``git diff`` command. If there are changes to other classes than the one you are planning to document, please commit those changes first before starting to edit the template:
+The XML files in doc/classes should then be up-to-date with current Godot Engine features. You can then check what changed using the ``git diff`` command. If there are changes to other classes than the one you are planning to document, please commit those changes first before starting to edit the template:
 
 ::
 
@@ -153,7 +157,7 @@ When it's done, you can ask for a Pull Request via the GitHub UI of your Godot f
 
 .. warning::
 
-    Although you can edit files on GitHub, it's not recommended. As hundreds of contributors work on Godot, the git history must stay clean. Each commit should bundle all related improvements you make to the class reference, a new feature, bug fixes... When you edit from GitHub, it will create a new branch and a Pull Request every time you want to save it. If a few days pass before your changes get a review, you won't be able to update to the latest version of the repository cleanly. Also, it's harder to keep clean indents from GitHub. And they're very important in the docs.
+    Although you can edit files on GitHub, it's not recommended. As hundreds of contributors work on Godot, the Git history must stay clean. Each commit should bundle all related improvements you make to the class reference, a new feature, bug fixes... When you edit from GitHub, it will create a new branch and a Pull Request every time you want to save it. If a few days pass before your changes get a review, you won't be able to update to the latest version of the repository cleanly. Also, it's harder to keep clean indents from GitHub. And they're very important in the docs.
 
     TL;DR: If you don't know what you're doing exactly, do not edit files from GitHub.
 
@@ -252,6 +256,8 @@ Godot's class reference supports BBcode-like tags. They add nice formatting to t
 +---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
 | [code] [/code]            | Monospace                      | Some [code]monospace[/code] text. | Some ``monospace`` text.                          |
 +---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
+| [kbd] [/kbd]              | Keyboard/mouse shortcut        | Some [kbd]Ctrl + C[/kbd] key.     | Some :kbd:`Ctrl + C` key.                         |
++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
 | [codeblock] [/codeblock]  | Multiline preformatted block   | *See below.*                      | *See below.*                                      |
 +---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
 

community/tutorials.rst

@@ -35,6 +35,7 @@ Video tutorials
 - `TheBuffED <https://www.youtube.com/watch?v=ygGaN1EOQEA&list=PLvN5Z3tTxXEDfQkt4Frg6ALirespSwZd7>`_ (2D, GDScript).
 - `Code with Tom <https://www.youtube.com/playlist?list=PLiUQR4U_J9ec0k91iHPme_qtfS1nrWF3W>`_ (2D and 3D, GDScript).
 - `BornCG <https://www.youtube.com/playlist?list=PLda3VoSoc_TSBBOBYwcmlamF1UrjVtccZ>`_ (3D, GDScript).
+- `Gonkee <https://www.youtube.com/channel/UCJqCPFHdbc6443G3Sz6VYDw>`_ (2D, 3D, GDScript, Shaders).
 
 Text tutorials
 --------------

development/compiling/compiling_for_osx.rst

@@ -48,10 +48,23 @@ To create an ``.app`` bundle like in the official builds, you need to use the
 template located in ``misc/dist/osx_tools.app``. Typically, for an optimized
 editor binary built with ``scons p=osx target=release_debug``::
 
-    user@host:~/godot$ cp -r misc/dist/osx_tools.app ./Godot.app
-    user@host:~/godot$ mkdir -p Godot.app/Contents/MacOS
-    user@host:~/godot$ cp bin/godot.osx.tools.64 Godot.app/Contents/MacOS/Godot
-    user@host:~/godot$ chmod +x Godot.app/Contents/MacOS/Godot
+    cp -r misc/dist/osx_tools.app ./Godot.app
+    mkdir -p Godot.app/Contents/MacOS
+    cp bin/godot.osx.tools.64 Godot.app/Contents/MacOS/Godot
+    chmod +x Godot.app/Contents/MacOS/Godot
+
+Compiling a headless/server build
+---------------------------------
+
+To compile a *headless* build which provides editor functionality to export
+projects in an automated manner, use::
+
+    scons platform=server tools=yes target=release_debug --jobs=$(sysctl -n hw.logicalcpu)
+
+To compile a *server* build which is optimized to run dedicated game servers,
+use::
+
+    scons platform=server tools=no target=release --jobs=$(sysctl -n hw.logicalcpu)
 
 Cross-compiling for macOS from Linux
 ------------------------------------
@@ -65,7 +78,7 @@ Clone the `OSXCross repository <https://github.com/tpoechtrager/osxcross>`__
 somewhere on your machine (or download a ZIP file and extract it somewhere),
 e.g.::
 
-    user@host:~$ git clone --depth=1 https://github.com/tpoechtrager/osxcross.git "$HOME/osxcross"
+    git clone --depth=1 https://github.com/tpoechtrager/osxcross.git "$HOME/osxcross"
 
 1. Follow the instructions to package the SDK:
    https://github.com/tpoechtrager/osxcross#packaging-the-sdk
@@ -76,12 +89,12 @@ After that, you will need to define the ``OSXCROSS_ROOT`` as the path to
 the OSXCross installation (the same place where you cloned the
 repository/extracted the zip), e.g.::
 
-    user@host:~$ export OSXCROSS_ROOT="$HOME/osxcross"
+    export OSXCROSS_ROOT="$HOME/osxcross"
 
 Now you can compile with SCons like you normally would::
 
-    user@host:~/godot$ scons platform=osx
+    scons platform=osx
 
 If you have an OSXCross SDK version different from the one expected by the SCons buildsystem, you can specify a custom one with the ``osxcross_sdk`` argument::
 
-    user@host:~/godot$ scons platform=osx osxcross_sdk=darwin15
+    scons platform=osx osxcross_sdk=darwin15

development/compiling/compiling_for_uwp.rst

@@ -18,11 +18,11 @@ Requirements
 
 .. note:: The ANGLE repo by Microsoft has been discontinued and the
           ``ms_master`` branch has been cleared out.
-          
+
           As a temporary workaround however, it is still possible to
           download an older state of the source code via commit
           `c61d048 <https://github.com/microsoft/angle/tree/c61d0488abd9663e0d4d2450db7345baa2c0dfb6>`__.
-          
+
           This page will eventually be updated in the future to reflect
           the new build instructions.
 

development/compiling/compiling_for_windows.rst

@@ -17,7 +17,7 @@ For compiling under Windows, the following is required:
 - `MinGW-w64 <http://mingw-w64.org/>`__ with GCC can be used as an alternative to
   Visual Studio. Be sure to install/configure it to use the ``posix`` thread model.
 - `Python 3.5+ <https://www.python.org/downloads/windows/>`_.
-- `SCons 3.0 <https://www.scons.org>`_ build system. If using Visual Studio 2019,
+- `SCons 3.0 <https://www.scons.org/>`_ build system. If using Visual Studio 2019,
   you need at least SCons 3.1.1.
 - *Optional* - `yasm <https://yasm.tortall.net/>`_ (for WebM SIMD optimizations)
 
@@ -33,19 +33,26 @@ For compiling under Windows, the following is required:
                   mingw-w64-x86_64-gcc mingw-w64-x86_64-yasm \
                   mingw-w64-i686-python3-pip mingw-w64-i686-gcc \
                   mingw-w64-i686-yasm make
-              
+
           For each MSYS2 MinGW subsystem, you should then run
           `pip install scons` in its shell.
 
 .. seealso:: For a general overview of SCons usage for Godot, see
              :ref:`doc_introduction_to_the_buildsystem`.
 
+Setting up Python
+-----------------
+
+First you need to install Python 3.5 or newer. Make sure to enable the option
+to add Python to the ``PATH`` in the Python installer. The SCons installer
+should then detect and use the existing Python installation.
+
 Setting up SCons
 ----------------
 
-First, make sure to enable the option to add Python to the ``PATH`` in
-the Python installer. The SCons installer should then detect and use
-the existing Python installation.
+To install SCons open the command prompt and run the following command.
+
+``python -m pip install scons``
 
 To check whether you have installed Python and SCons correctly, you can
 type ``python --version`` and ``scons --version`` into a command prompt
@@ -209,8 +216,8 @@ To make sure you are doing things correctly, executing the following in
 the shell should result in a working compiler (the version output may
 differ based on your system)::
 
-    user@host:~$ ${MINGW32_PREFIX}gcc --version
-    i686-w64-mingw32-gcc (GCC) 6.1.0 20160427 (Mageia MinGW 6.1.0-1.mga6)
+    ${MINGW32_PREFIX}gcc --version
+    # i686-w64-mingw32-gcc (GCC) 6.1.0 20160427 (Mageia MinGW 6.1.0-1.mga6)
 
 Troubleshooting
 ~~~~~~~~~~~~~~~

development/compiling/compiling_for_x11.rst

@@ -92,7 +92,7 @@ Start a terminal, go to the root dir of the engine source code and type:
 
 ::
 
-    user@host:~/godot$ scons -j8 platform=x11
+    scons -j8 platform=x11
 
 A good rule of thumb for the ``-j`` (*jobs*) flag, is to have at least as many
 threads compiling Godot as you have cores in your CPU, if not one or two more.
@@ -109,7 +109,7 @@ manager.
 
     ::
 
-        user@host:~/godot$ scons platform=x11 use_llvm=yes
+        scons platform=x11 use_llvm=yes
 
     Using Clang appears to be a requirement for OpenBSD, otherwise fonts
     would not build.
@@ -128,6 +128,19 @@ manager.
           :ref:`doc_data_paths_self_contained_mode` by creating a file called
           ``._sc_`` or ``_sc_`` in the ``bin/`` folder.
 
+Compiling a headless/server build
+---------------------------------
+
+To compile a *headless* build which provides editor functionality to export
+projects in an automated manner, use::
+
+    scons -j8 platform=server tools=yes target=release_debug
+
+To compile a *server* build which is optimized to run dedicated game servers,
+use::
+
+    scons -j8 platform=server tools=no target=release
+
 Building export templates
 -------------------------
 
@@ -146,15 +159,15 @@ following parameters:
 
 ::
 
-    user@host:~/godot$ scons platform=x11 tools=no target=release bits=32
-    user@host:~/godot$ scons platform=x11 tools=no target=release_debug bits=32
+    scons platform=x11 tools=no target=release bits=32
+    scons platform=x11 tools=no target=release_debug bits=32
 
 -  (64 bits)
 
 ::
 
-    user@host:~/godot$ scons platform=x11 tools=no target=release bits=64
-    user@host:~/godot$ scons platform=x11 tools=no target=release_debug bits=64
+    scons platform=x11 tools=no target=release bits=64
+    scons platform=x11 tools=no target=release_debug bits=64
 
 Note that cross-compiling for the opposite bits (64/32) as your host
 platform is not always straight-forward and might need a chroot environment.
@@ -197,7 +210,7 @@ the default GCC + GNU ld setup:
 To do so, install Clang and the ``lld`` package from your distribution's package manager
 then use the following SCons command::
 
-    user@host:~/godot$ scons platform=x11 use_llvm=yes use_lld=yes
+    scons platform=x11 use_llvm=yes use_lld=yes
 
 It's still recommended to use GCC for production builds as they can be compiled using
 link-time optimization, making the resulting binaries smaller and faster.

development/compiling/introduction_to_the_buildsystem.rst

@@ -62,7 +62,7 @@ It will then start building for the target platform right away.
 
 To list the available target platforms, use ``scons platform=list``::
 
-    user@host:~/godot$ scons platform=list
+    scons platform=list
     scons: Reading SConscript files ...
     The following platforms are available:
 
@@ -79,7 +79,7 @@ To build for a platform (for example, x11), run with the ``platform=`` (or
 
 ::
 
-    user@host:~/godot$ scons platform=x11
+    scons platform=x11
 
 This will start the build process, which will take a while. If you want
 SCons to build faster, use the ``-j <cores>`` parameter to specify how many
@@ -90,7 +90,7 @@ Example for using 4 cores:
 
 ::
 
-    user@host:~/godot$ scons platform=x11 -j 4
+    scons platform=x11 -j 4
 
 Resulting binary
 ----------------
@@ -102,7 +102,7 @@ generally with this naming convention::
 
 For the previous build attempt, the result would look like this::
 
-    user@host:~/godot$ ls bin
+    ls bin
     bin/godot.x11.tools.64
 
 This means that the binary is for X11, is not optimized, has tools (the
@@ -192,6 +192,75 @@ features to include/disable.
 Check the output of ``scons --help`` for details about each option for
 the version you are willing to compile.
 
+.. _doc_overriding_build_options:
+
+Overriding the build options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using a file
+^^^^^^^^^^^^
+
+The default ``custom.py`` file can be created at the root of the Godot Engine
+source to initialize any SCons build options passed via the command line:
+
+.. code-block:: python
+
+    # custom.py
+    
+    optimize = "size"
+    module_mono_enabled = "yes"
+    use_llvm = "yes"
+    extra_suffix = "game_title"
+
+You can also disable some of the builtin modules before compiling, saving some
+time it takes to build the engine, see :ref:`doc_optimizing_for_size` page for more details.
+
+Another custom file can be specified explicitly with the ``profile`` command
+line option, both overriding the default build configuration:
+
+.. code-block:: shell
+
+    scons profile=path/to/custom.py
+
+.. note:: Build options set from the file can be overridden by the command line
+          options.
+
+It's also possible to override the options conditionally:
+
+.. code-block:: python
+
+    # custom.py
+
+    import version
+
+    # Override options specific for Godot 3.x and 4.x versions.
+    if version.major == 3:
+        pass
+    elif version.major == 4:
+        pass
+
+Using the SCONSFLAGS
+^^^^^^^^^^^^^^^^^^^^
+
+``SCONSFLAGS`` is an environment variable which is used by the SCons to set the
+options automatically without having to supply them via the command line.
+
+For instance, you may want to build Godot in parallel with the aforementioned
+``-j`` option for all the future builds:
+
+.. tabs::
+ .. code-tab:: bash Linux/macOS
+
+     export SCONSFLAGS="-j4"
+
+ .. code-tab:: bat Windows (cmd)
+
+     set SCONSFLAGS=-j4
+
+ .. code-tab:: powershell Windows (powershell)
+
+     $env:SCONSFLAGS="-j4"
+
 Export templates
 ----------------
 

development/compiling/optimizing_for_size.rst

@@ -63,6 +63,52 @@ modules and see which ones you actually still need for your game (e.g. you
 might want to keep networking-related modules, regex support, or theora/webm
 to play videos).
 
+Alternatively, you can supply a list of disabled modules by creating
+``custom.py`` at the root of the source, with the contents similar to the
+following:
+
+.. code-block:: python
+
+    # custom.py
+    
+    module_arkit_enabled = "no"
+    module_assimp_enabled = "no"
+    module_bmp_enabled = "no"
+    module_bullet_enabled = "no"
+    module_camera_enabled = "no"
+    module_csg_enabled = "no"
+    module_dds_enabled = "no"
+    module_enet_enabled = "no"
+    module_etc_enabled = "no"
+    module_gdnative_enabled = "no"
+    module_gridmap_enabled = "no"
+    module_hdr_enabled = "no"
+    module_jsonrpc_enabled = "no"
+    module_mbedtls_enabled = "no"
+    module_mobile_vr_enabled = "no"
+    module_opensimplex_enabled = "no"
+    module_opus_enabled = "no"
+    module_pvr_enabled = "no"
+    module_recast_enabled = "no"
+    module_regex_enabled = "no"
+    module_squish_enabled = "no"
+    module_svg_enabled = "no"
+    module_tga_enabled = "no"
+    module_theora_enabled = "no"
+    module_tinyexr_enabled = "no"
+    module_upnp_enabled = "no"
+    module_vhacd_enabled = "no"
+    module_vorbis_enabled = "no"
+    module_webm_enabled = "no"
+    module_webp_enabled = "no"
+    module_webrtc_enabled = "no"
+    module_websocket_enabled = "no"
+    module_xatlas_unwrap_enabled = "no"
+    
+.. seealso::
+
+    :ref:`doc_overriding_build_options`.
+
 Optimizing for size instead of speed
 ------------------------------------
 

development/cpp/configuring_an_ide.rst

@@ -1,404 +0,0 @@
-.. _doc_configuring_an_ide:
-
-Configuring an IDE
-==================
-
-We assume that you have already `cloned <https://github.com/godotengine/godot>`_
-and :ref:`compiled <toc-devel-compiling>` Godot.
-
-You can easily develop Godot with any text editor and by invoking ``scons``
-on the command line, but if you want to work with an IDE (Integrated
-Development Environment), here are setup instructions for some popular ones:
-
-- :ref:`Qt Creator <doc_configuring_an_ide_qtcreator>` (all desktop platforms)
-- :ref:`Kdevelop <doc_configuring_an_ide_kdevelop>` (all desktop platforms)
-- :ref:`Xcode <doc_configuring_an_ide_xcode>` (macOS)
-- :ref:`Visual Studio <doc_configuring_an_ide_vs>` (Windows)
-- :ref:`Visual Studio Code<doc_configuring_an_ide_vscode>` (all desktop platforms)
-- :ref:`Android Studio<doc_configuring_an_ide_android_studio>` (all desktop platforms)
-- :ref:`CLion<doc_configuring_an_ide_clion>` (all desktop platforms)
-
-It is possible to use other IDEs, but their setup is not documented yet.
-
-.. _doc_configuring_an_ide_qtcreator:
-
-Qt Creator
-----------
-
-Importing the project
-^^^^^^^^^^^^^^^^^^^^^
-
--  Choose *New Project* -> *Import Project* -> *Import Existing Project*.
-
-.. image:: img/qtcreator-new-project.png
-
--  Set the path to your Godot root directory and enter the project name.
-
-.. image:: img/qtcreator-set-project-path.png
-
--  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 macOS. Click "Next".
-
-.. image:: img/qtcreator-apply-import-filter.png
-
--  Click *Finish*.
--  Add a line containing ``.`` to *project_name.includes* to get working code completion.
-
-.. image:: img/qtcreator-project-name-includes.png
-
-Build and run
-^^^^^^^^^^^^^
-
-Build configuration:
-
--  Click on *Projects* and open the *Build* tab.
--  Delete the pre-defined ``make`` build step.
-
-.. image:: img/qtcreator-projects-build.png
-
--  Click *Add Build Step* -> *Custom Process Step*.
-
-.. 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, so you may have to
-   use the full path to the SCons binary.
--  Fill the *Arguments* field with your compilation options. (e.g.: ``p=x11 target=debug -j 4``)
-
-.. image:: img/qtcreator-set-scons-command.png
-
-Run configuration:
-
--  Open the *Run* tab.
--  Point the *Executable* to your compiled Godot binary (e.g: ``%{buildDir}/bin/godot.x11.opt.tools.64``)
--  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.
-
-.. image:: img/qtcreator-run-command.png
-
-Updating sources after pulling latest commits
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-As a developer you usually want to frequently pull the latest commits
-from the upstream git repository or a specific fork etc. However, this
-brings a little 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
-experience coding in it. A simple way to check is to right click
-at your root folder in the "Projects View" and click on "Edit files..."
-
-.. image:: img/qtcreator-edit-files-menu.png
-
-Now a new dialog should appear that is similar in functionality to the one in the third step
-of the "Importing the project" section. 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. A simple click on "Ok" and you're ready to continue your work.
-
-.. image:: img/qtcreator-edit-files-dialog.png
-
-Code style configuration
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Developers must follow the project's :ref:`code style <doc_code_style_guidelines>`
-and IDE should help them to do it. By default, Qt Creator does use spaces for indentation
-which is incorrect for Godot project. You can change this behavior by
-changing the "Code Style" in *Options* -> *C++*.
-
-.. image:: img/qtcreator-options-cpp.png
-
-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
-
-.. _doc_configuring_an_ide_kdevelop:
-
-KDevelop
---------
-
-`KDevelop <https://www.kdevelop.org>`_ is a free, open source IDE for all desktop platforms.
-
-You can find a video tutorial `here <https://www.youtube.com/watch?v=yNVoWQi9TJA>`_.
-Or you may follow this text version tutorial.
-
-Start by opening KDevelop and choosing "open project".
-
-.. image:: img/kdevelop_newproject.png
-
-Choose the directory where you cloned Godot.
-
-On the next screen, choose "Custom Build System" for the *Project manager*.
-
-.. image:: img/kdevelop_custombuild.png
-
-Now that the project has been imported, open the project configuration.
-
-.. image:: img/kdevelop_openconfig.png
-
-Add the following includes/imports:
-
-.. code-block:: none
-
-    .  // a dot to indicate the root of the Godot project
-    core/
-    core/os/
-    core/math/
-    drivers/
-    platform/x11/  // make that platform/osx/ if you're using macOS
-
-.. image:: img/kdevelop_addincludes.png
-
-Apply the changes.
-
-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=x11 target=debug`` (``platform=osx``
-if you're on macOS) as the arguments.
-
-.. image:: img/kdevelop_buildconfig.png
-
-Next we need to tell KDevelop where to find the binary.
-From the "Run" menu, choose "Configure Launches".
-
-.. image:: img/kdevelop_configlaunches.png
-
-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/`` sub-directory and should be named something like
-``godot.x11.tools.64`` (the name could be different depending on your
-platform and depending on your build options).
-
-.. image:: img/kdevelop_configlaunches2.png
-
-That's it! Now you should be good to go :)
-
-
-.. _doc_configuring_an_ide_xcode:
-
-Xcode
------
-
-Project setup
-^^^^^^^^^^^^^
-
-- Create an Xcode external build project anywhere
-
-.. image:: img/xcode_1_create_external_build_project.png
-
-- Set the *Build tool* to the path to scons
-
-Modify Build Target's Xcode Info Tab:
-
-- Set *Arguments* to something like: platform=osx tools=yes bits=64 target=debug
-- Set *Directory* to the path to Godot's source folder. Keep it blank if project is already there.
-- You may uncheck *Pass build settings in environment*
-
-.. image:: img/xcode_2_configure_scons.png
-
-Add a Command Line Target:
-
-- Go to Xcode File > New > Target... and add a new Xcode command line target
-
-.. image:: img/xcode_3_add_new_target.png
-
-.. image:: img/xcode_4_select_command_line_target.png
-
-- 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 search for *Header Search Paths*
-- Set *Header Search Paths* to an absolute path to Godot's source folder
-- Make it recursive by adding two \*'s to the end of the path
-- e.g. ``/Users/me/repos/godot-source/\**``
-
-Add Godot Source to the Project:
-
-- Drag and drop Godot source into project file browser.
-- Uncheck *Create External Build System*
-
-.. image:: img/xcode_5_after_add_godot_source_to_project.png
-
-- Click Next
-- Select *create groups*
-
-.. image:: img/xcode_6_after_add_godot_source_to_project_2.png
-
-- Check off only your command line target in the *Add to targets* section
-- Click finish. Xcode will now index the files.
-- Grab a cup of coffee... Maybe make something to eat, too
-- You should have jump to definition, auto completion, and full syntax highlighting when it is done.
-
-Scheme setup
-^^^^^^^^^^^^
-
-Edit Build Scheme of External Build Target:
-
-- Open scheme editor of 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 ``${PROJECT_DIR}`` variable.
-
-.. image:: img/xcode_7_setup_build_post_action.png
-
-- Write a script that gives the binary a name that Xcode will recognize
-- e.g. ``ln -f ${PROJECT_DIR}/godot/bin/godot.osx.tools.64 ${PROJECT_DIR}/godot/bin/godot``
-- Build the external build target
-
-Edit Run Scheme of External Build Target:
-
-- Open the scheme editor again
-- Click Run
-
-.. image:: img/xcode_8_setup_run_scheme.png
-
-- Set the *Executable* to the file you linked in your post build action script
-- Check *Debug executable* if it isn't already
-- You can go to *Arguments* tab and add an -e and a -path to a project to debug the editor
-  not the project selection screen
-
-Test it:
-
-- Set a breakpoint in platform/osx/godot_main_osx.mm
-- It should break at the point!
-
-
-.. _doc_configuring_an_ide_vs:
-
-Visual Studio
--------------
-
-Visual Studio Community is free for non-commercial use and 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/>`__.
-
-Setup
-^^^^^
-
-To start developing with Visual Studio, follow these steps:
-
-- Open the Visual Studio Installer and install the C++ package:
-
-.. image:: img/vs_1_install_cpp_package.png
-
-- Open a Command Prompt or PowerShell window, use ``cd`` to reach the Godot source
-  directory and run ``scons platform=windows vsproj=yes``.
-
-- 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
-^^^^^^^^^
-
-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.
-
-          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.
-
-To overcome this, you need to edit the debugging command line arguments in VS. In your
-project, click **Project > Project Properties**:
-
-.. image:: img/vs_2_project_properties.png
-
-Then add this to the command arguments:
-
-.. 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).
-
-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
-start debugging.
-
-.. image:: img/vs_4_debugging_main.png
-
-
-.. _doc_configuring_an_ide_vscode:
-
-Visual Studio Code
-------------------
-
-- Ensure that C/C++ extension is installed. You can find instructions in `docs <https://code.visualstudio.com/docs/languages/cpp>`_.
-
-- Open cloned godot folder in VS Code with ``File > Open Folder...``
-
-In order to build the project, you need two configuration files: *launch.json* and *tasks.json*.
-To create them:
-
-- Open *Debug* view by pressing :kbd:`Ctrl + Shift + D` and select 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
-
-(Note that *godot.x11.tools.64* in "program" value might be named differently on macOS or Windows)
-
-- Create *tasks.json* by starting the Debug process with :kbd:`F5`. VS Code will show a dialog with a *Configure Task* button. Tap it and select *Create tasks.json file from template*, then select *Others*
-
-- Update *tasks.json* to match:
-
-.. image:: img/vscode_3_tasks.json.png
-
-(Note that *platform=x11* will be different for macOX and Windows)
-
-- 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 that some dependencies are missing. Check :ref:`Compiling for X11 (Linux, \*BSD) <doc_compiling_for_x11>`
-
-
-.. _doc_configuring_an_ide_android_studio:
-
-Android Studio
---------------
-
-`Android Studio <https://developer.android.com/studio>`_ is a `JetBrains <https://www.jetbrains.com/>`_ IDE for Android development. It has a feature-rich editor which supports Java and C/C++, so it can be used for development of the Godot core engine, and Android platform codebases.
-
-Project setup
-^^^^^^^^^^^^^
-
-- From the Android Studio *Welcome to Android Studio* window, select *Open an existing Android Studio project*
-
-.. image:: img/android_studio_setup_project_1.png
-
-- Navigate to ``<godot root directory>/platform/android/java`` and select the ``settings.gradle`` gradle file.
-- Android Studio will import and index the project.
-- To build the project, follow the :ref:`compiling instructions <toc-devel-compiling>`.
-
-.. _doc_configuring_an_ide_clion:
-
-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 and not 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.
-
-- Choose *File* -> *Open*.
-
-- Navigation to your Godot Git clone, and 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
-
-- If this popup window appears, select *This window* to open the project.
-
-.. image:: img/clion_2_this_window.png
-
-- Choose *Tools* -> *CMake* -> *Change Project Root* and select the root Godot folder.
-
-.. image:: img/clion_3_change_project_root.png
-
-- You should be now be able to see all the project files. Autocomplete should work, when the project finish indexing.

development/cpp/configuring_an_ide/android_studio.rst

@@ -0,0 +1,21 @@
+.. _doc_configuring_an_ide_android_studio:
+
+Android Studio
+==============
+
+`Android Studio <https://developer.android.com/studio>`_ is a free
+`JetBrains <https://www.jetbrains.com/>`_ IDE for Android development.
+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**.
+
+.. image:: img/android_studio_setup_project_1.png
+
+- Navigate to ``<Godot root directory>/platform/android/java`` and select the ``settings.gradle`` gradle file.
+- Android Studio will import and index the project.
+- To build the project, follow the :ref:`compiling instructions <toc-devel-compiling>`.
+
+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/clion.rst

@@ -0,0 +1,34 @@
+.. _doc_configuring_an_ide_clion:
+
+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
+
+- If this popup window appears, select **This Window** to open the project:
+
+.. image:: img/clion_2_this_window.png
+
+- Choose **Tools > CMake >Change Project Root** and select the root Godot folder.
+
+.. image:: img/clion_3_change_project_root.png
+
+- You should be now be able to see all the project files. Autocomplete should
+  work once the project has finished indexing.
+
+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/index.rst

@@ -0,0 +1,23 @@
+Configuring an IDE
+==================
+
+We assume that you have already `cloned <https://github.com/godotengine/godot>`_
+and :ref:`compiled <toc-devel-compiling>` Godot.
+
+You can easily develop Godot with any text editor and by invoking ``scons``
+on the command line, but if you want to work with an IDE (Integrated
+Development Environment), here are setup instructions for some popular ones:
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-devel-configuring_an_ide
+
+   android_studio
+   clion
+   kdevelop
+   qt_creator
+   visual_studio_code
+   visual_studio
+   xcode
+
+It is possible to use other IDEs, but their setup is not documented yet.

development/cpp/configuring_an_ide/kdevelop.rst

@@ -0,0 +1,58 @@
+.. _doc_configuring_an_ide_kdevelop:
+
+KDevelop
+========
+
+`KDevelop <https://www.kdevelop.org>`_ is a free, open source IDE for all desktop platforms.
+
+Start by opening KDevelop and choosing **Open Project**.
+
+.. image:: img/kdevelop_newproject.png
+
+Choose the directory where you cloned Godot.
+
+On the next screen, choose **Custom Build System** for the **Project Manager**.
+
+.. image:: img/kdevelop_custombuild.png
+
+Now that the project has been imported, open the project configuration.
+
+.. image:: img/kdevelop_openconfig.png
+
+Add the following includes/imports:
+
+.. code-block:: none
+
+    .  // 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
+
+.. image:: img/kdevelop_addincludes.png
+
+Apply the changes.
+
+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.
+
+.. image:: img/kdevelop_buildconfig.png
+
+Next, we need to tell KDevelop where to find the binary.
+From the **Run** menu, choose **Configure Launches**.
+
+.. image:: img/kdevelop_configlaunches.png
+
+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).
+
+.. image:: img/kdevelop_configlaunches2.png
+
+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

@@ -0,0 +1,105 @@
+.. _doc_configuring_an_ide_qtcreator:
+
+Qt Creator
+==========
+
+Qt Creator is a free, open source IDE for all desktop platforms.
+
+Importing the project
+---------------------
+
+- Choose **New Project > Import Project > Import Existing Project**.
+
+.. image:: img/qtcreator-new-project.png
+
+- Set the path to your Godot root directory and enter the project name.
+
+.. image:: img/qtcreator-set-project-path.png
+
+- 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 platform development,
+  ``*.mm`` for macOS platform development. Click **Next**.
+
+.. image:: img/qtcreator-apply-import-filter.png
+
+- Click **Finish**.
+- Add a line containing ``.`` to ``project_name.includes`` to get working
+  code completion.
+
+.. image:: img/qtcreator-project-name-includes.png
+
+Build and run
+--------------
+
+Build configuration:
+
+- 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**.
+
+.. 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``).
+
+.. image:: img/qtcreator-set-scons-command.png
+
+Run configuration:
+
+- 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.
+
+.. image:: img/qtcreator-run-command.png
+
+Updating sources after pulling latest commits
+---------------------------------------------
+
+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...**.
+
+.. image:: img/qtcreator-edit-files-menu.png
+
+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.
+
+.. image:: img/qtcreator-edit-files-dialog.png
+
+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
+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
+
+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
+
+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

@@ -0,0 +1,64 @@
+.. _doc_configuring_an_ide_vs:
+
+Visual Studio
+=============
+
+Visual Studio Community is a Windows-only IDE 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/>`__.
+
+Setup
+-----
+
+To start developing with Visual Studio, follow these steps:
+
+- Open the Visual Studio Installer and install the C++ package:
+
+.. image:: img/vs_1_install_cpp_package.png
+
+- Open a Command Prompt or PowerShell window, use ``cd`` to reach the Godot source
+  directory and run ``scons platform=windows vsproj=yes``.
+
+- 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
+---------
+
+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.
+
+          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.
+
+To overcome this, you need to edit the debugging command line arguments in VS. In your
+project, click **Project > Project Properties**:
+
+.. image:: img/vs_2_project_properties.png
+
+Then add this to the command arguments:
+
+.. 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).
+
+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
+start debugging.
+
+.. image:: img/vs_4_debugging_main.png
+
+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

@@ -0,0 +1,49 @@
+.. _doc_configuring_an_ide_vscode:
+
+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/>`__.
+
+
+- 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
+  **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`.
+
+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

@@ -0,0 +1,95 @@
+.. _doc_configuring_an_ide_xcode:
+
+Xcode
+=====
+
+Xcode is a free macOS-only IDE. You can download it from the Mac App Store.
+
+Project setup
+-------------
+
+- Create an Xcode external build project anywhere.
+
+.. image:: img/xcode_1_create_external_build_project.png
+
+Go to the build target's **Info** tab, then:
+
+- 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**.
+
+.. image:: img/xcode_2_configure_scons.png
+
+Add a Command Line Tool target which will be used for indexing the project:
+
+- In Xcode's menu, choose **File > New > Target...** and add a new Xcode
+  command line tool target.
+
+.. image:: img/xcode_3_add_new_target.png
+
+.. image:: img/xcode_4_select_command_line_target.png
+
+- 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/**``.
+
+Add the Godot source to the project:
+
+- Drag and drop Godot source into the project file browser.
+- Uncheck **Create external build system project**.
+
+.. image:: img/xcode_5_after_add_godot_source_to_project.png
+
+- Click **Next**.
+- Select **Create groups**.
+
+.. image:: img/xcode_6_after_add_godot_source_to_project_2.png
+
+- 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.
+- Once Xcode is done indexing, you should have jump-to-definition,
+  autocompletion, and full syntax highlighting.
+
+Scheme setup
+------------
+
+To enable debugging support, edit the external build target's build scheme:
+
+- 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.
+
+.. image:: img/xcode_7_setup_build_post_action.png
+
+- 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.
+
+Edit the external build target's Run scheme:
+
+- Open the scheme editor again.
+- Click **Run**.
+
+.. image:: img/xcode_8_setup_run_scheme.png
+
+- 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).
+
+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.
+
+If you run into any issues, ask for help in one of
+`Godot's community channels <https://godotengine.org/community>`__.

development/cpp/custom_modules_in_cpp.rst

@@ -311,8 +311,8 @@ during runtime with the ``LD_LIBRARY_PATH`` environ variable:
 
 .. code-block:: shell
 
-    user@host:~/godot$ export LD_LIBRARY_PATH=`pwd`/bin/
-    user@host:~/godot$ ./bin/godot*
+    export LD_LIBRARY_PATH=`pwd`/bin/
+    ./bin/godot*
 
 **note**: Pay attention you have to ``export`` the environ variable otherwise
 you won't be able to play your project from within the editor.
@@ -357,7 +357,7 @@ shared module as target in the SCons command:
 
 .. code-block:: shell
 
-    user@host:~/godot$ scons summator_shared=yes platform=x11 bin/libsummator.x11.tools.64.so
+    scons summator_shared=yes platform=x11 bin/libsummator.x11.tools.64.so
 
 Writing custom documentation
 ----------------------------
@@ -373,54 +373,87 @@ There are several steps in order to setup custom docs for the module:
 1. Make a new directory in the root of the module. The directory name can be
    anything, but we'll be using the ``doc_classes`` name throughout this section.
 
-2. Append the following code snippet to ``config.py``:
+2. Now, we need to edit ``config.py``, add the following snippet:
 
    .. code-block:: python
 
-       def get_doc_classes():
-           return [
-               "ClassName",
-           ]
+        def get_doc_path():
+            return "doc_classes"
 
-       def get_doc_path():
-           return "doc_classes"
+        def get_doc_classes():
+            return [
+                "Summator",
+            ]
+
+The ``get_doc_path()`` function is used by the build system to determine
+the location of the docs. In this case, they will be located in the 
+``modules/summator/doc_classes`` directory. If you don't define this,
+the doc path for your module will fall back to the main ``doc/classes`` 
+directory.
 
 The ``get_doc_classes()`` method is necessary for the build system to
-know which documentation classes of the module must be merged, since the module
-may contain several classes. Replace ``ClassName`` with the name of the class
-you want to write documentation for. If you need docs for more than one class,
-append those as well.
+know which registered classes belong to the module. You need to list all of your 
+classes here. The classes that you don't list will end up in the 
+main ``doc/classes`` directory.
 
-The ``get_doc_path()`` method is used by the build system to determine
-the location of the docs. In our case, they will be located in the ``doc_classes``
-directory.
+.. tip::
 
-3. Run command:
+    You can use git to check if you have missed some of your classes by checking the 
+    untracked files with ``git status``. For example::
 
-   .. code-block:: shell
+        user@host:~/godot$ git status
 
-      godot --doctool <path>
+    Example output::
 
-This will dump the engine API reference to the given ``<path>`` in XML format.
-Notice that you'll need to configure your ``PATH`` to locate Godot's executable,
-and make sure that you have write access rights. If not, you might encounter an
-error similar to the following:
+        Untracked files:
+            (use "git add <file>..." to include in what will be committed)
+            
+            doc/classes/MyClass2D.xml
+            doc/classes/MyClass4D.xml
+            doc/classes/MyClass5D.xml
+            doc/classes/MyClass6D.xml
+            ...
+    
 
-.. code-block:: console
+3. Now we can generate the documentation:
 
-    ERROR: Can't write doc file: docs/doc/classes/@GDScript.xml
-       At: editor/doc/doc_data.cpp:956
+We can do this via running Godot's doctool i.e. ``godot --doctool <path>``,
+which will dump the engine API reference to the given ``<path>`` in XML format.
+
+In our case we'll point it to the root of the cloned repository. You can point it
+to an another folder, and just copy over the files that you need.
+
+Run command:
+
+   ::
 
-4. Get generated doc file from ``godot/doc/classes/ClassName.xml``
+      user@host:~/godot/bin$ ./bin/<godot_binary> --doctool .
 
-5. Copy this file to ``doc_classes``, optionally edit it, then compile the engine.
+Now if you go to the ``godot/modules/summator/doc_classes`` folder, you will see 
+that it contains a ``Summator.xml`` file, or any other classes, that you referenced
+in your ``get_doc_classes`` function.
 
-The build system will fetch the documentation files from the ``doc_classes`` directory
-and merge them with the base types. Once the compilation process is finished,
-the docs will become accessible within the engine's built-in documentation system.
+Edit the file(s) following :ref:`doc_updating_the_class_reference` and recompile the engine.
+
+Once the compilation process is finished, the docs will become accessible within 
+the engine's built-in documentation system.
 
 In order to keep documentation up-to-date, all you'll have to do is simply modify
-one of the ``ClassName.xml`` files and recompile the engine from now on.
+one of the XML files and recompile the engine from now on.
+
+If you change your module's API, you can also re-extract the docs, they will contain
+the things that you previously added. Of course if you point it to your godot
+folder, make sure you don't lose work by extracting older docs from an older engine build 
+on top of the newer ones.
+
+Note that if you don't have write access rights to your supplied ``<path>``,
+you might encounter an error similar to the following:
+
+.. code-block:: console
+
+    ERROR: Can't write doc file: docs/doc/classes/@GDScript.xml
+       At: editor/doc/doc_data.cpp:956
+
 
 .. _doc_custom_module_icons: