Move docs contribution guides from the README to Contributing

- Edited building_the_manual to make the content more explicit
- Added some links to the README to help them get started contributing

README.md

@@ -15,134 +15,19 @@ configuration, you can install the
 [Dark Website Forcer](https://addons.mozilla.org/en-US/firefox/addon/dark-mode-website-switcher/)
 add-on.
 
-## Contributing changes
+## Contributing
 
-If you'd like to contribute to the official documentation, whether you want to improve existing pages or write a new one, we would ask you to follow our workflow and guidelines:
+All contributors are welcome to help on the Godot documentation.
 
-1. If you want to write a new page, please start by opening an issue or join the discussion on an open issue with your proposal. This ensures that your work matches our [content guidelines](https://docs.godotengine.org/en/latest/community/contributing/content_guidelines.html) and saves everyone time.
-2. Before writing, be sure to check out our style guides:
-    - [Writing style guide](https://docs.godotengine.org/en/latest/community/contributing/docs_writing_guidelines.html)
-    - [GDScript style guide](https://docs.godotengine.org/en/latest/tutorials/scripting/gdscript/gdscript_styleguide.html) if you write GDScript code.
-    - [C# style guide](https://docs.godotengine.org/en/latest/tutorials/scripting/c_sharp/c_sharp_style_guide.html) if you write C# code.
+To get started, head to the [Contributing section](https://docs.godotengine.org/en/latest/community/contributing/index.html) of the online manual. There, you will find all the information you need to write and submit changes.
 
-We also detail how to create new pages on the documentation [here](https://docs.godotengine.org/en/latest/community/contributing/documentation_guidelines.html).
-
-**Pull Requests should use the `master` branch by default. Only make Pull Requests against other branches (e.g. `3.2` or `2.1`) if your changes only apply to that version of Godot.**
-
-### Editing existing pages
-
-To edit an existing page, locate its .rst source file and open it in your favorite text editor. You can then commit the changes, push them to your fork and make a pull request.
-**Note that the pages in `classes/` should not be edited here, they are automatically generated from Godot's [XML class references](https://github.com/godotengine/godot/tree/master/doc/classes).**
-See [Contribute to the Class Reference](https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html) for details.
-
-### Adding new pages
-
-To add a new page, create a .rst file with a meaningful name in the section you want to add a file to, e.g. `tutorials/3d/light_baking.rst`. Write its content like you would do for any other file, and make sure to define a reference name for Sphinx at the beginning of the file (check other files for the syntax), based on the file name with a "doc_" prefix (e.g. `.. _doc_light_baking:`).
-
-You should then add your page to the relevant "toctree" (table of contents, e.g. `tutorials/3d/index.rst`). By convention, the files used to define the various levels of toctree are prefixed with an underscore, so in the above example the file should be referenced in `tutorials/3d/_3d_graphics.rst`. Add your new filename to the list on a new line, using a relative path and no extension, e.g. here `light_baking`.
-
-### Sphinx and reStructuredText syntax
-
-Check Sphinx's [reST Primer](https://www.sphinx-doc.org/en/stable/rest.html) and the [official reference](http://docutils.sourceforge.net/rst.html) for details on the syntax.
-
-Sphinx uses specific reST comments to do specific operations, like defining the table of contents (`:toctree:`) or cross-referencing pages. Check the [official Sphinx documentation](https://www.sphinx-doc.org/en/stable/index.html) for more details, or see how things are done in existing pages and adapt it to your needs.
-
-### Adding images and attachments
-
-To add images, please put them in an `img/` folder next to the .rst file with a meaningful name and include them in your page with:
-```rst
-.. image:: img/image_name.png
-```
-
-Similarly, you can include attachments (like assets as support material for a tutorial) by placing them into a `files/` folder next to the .rst file, and using this inline markup:
-```rst
-:download:`myfilename.zip <files/myfilename.zip>`
-```
-
-## Building with Sphinx
-
-To build the HTML website (or any other format supported by Sphinx, like PDF, EPUB or LaTeX), you need to install [Sphinx](https://www.sphinx-doc.org/) >= 1.3 as well as (for the HTML) the [readthedocs.org theme](https://github.com/snide/sphinx_rtd_theme).
-You also need to install the Sphinx extensions defined in `requirements.txt`.
-
-Those tools are best installed using [pip](https://pip.pypa.io), Python's module installer. The Python 3 version might be provided (on Linux distros) as `pip3` or `python3-pip`. You can then run:
-
-```sh
-pip install -r requirements.txt
-```
-
-You can then build the HTML documentation from the root folder of this repository with:
-
-```sh
-make html
-```
-
-or:
-
-```sh
-make SPHINXBUILD=~/.local/bin/sphinx-build html
-```
-
-Building the documentation requires at least 8 GB of RAM to be done without swapping. If you have at least 16 GB of RAM, you can speed up compilation by using:
-
-```bash
-# On Linux/macOS
-make html SPHINXOPTS=-j2
-
-# On Windows
-set SPHINXOPTS=-j2 && make html
-```
-
-The compilation might take some time as the `classes/` folder contains many files to parse.
-
-In case of a `MemoryError` or `EOFError`, you can remove the `classes/` folder and run `make` again. This will drop the class references from the final HTML documentation but will keep the rest intact. Make sure to avoid using `git add .` in this case when working on a pull request, or the whole `classes/` folder will be removed when you make a commit. See [#3157](https://github.com/godotengine/godot-docs/issues/3157) for more details.
-
-You can then test the changes live by opening `_build/html/index.html` in your favorite browser.
-
-### Building with Sphinx on Windows
-
-On Windows, you need to:
-* Download the Python installer [here](https://www.python.org/downloads/).
-* Install Python. Don't forget to check the "Add Python to PATH" box.
-* Use the above `pip` commands.
-
-Building is still done at the root folder of this repository using the provided `make.bat`:
-```sh
-make.bat html
-```
-
-Alternatively, you can build with this command instead:
-```sh
-sphinx-build -b html ./ _build
-```
-
-Note that during the first build, various installation prompts may appear and ask to install LaTeX plugins.
-Make sure you don't miss them, especially if they open behind other windows, else the build may appear to hang until you confirm these prompts.
-
-You could also install a normal `make` toolchain (for example via MinGW) and build the docs using the normal `make html`.
-
-### Building with Sphinx and virtualenv
-
-If you want your Sphinx installation scoped to the project, you can install it using virtualenv.
-Execute this from the root folder of this repository:
-
-```sh
-virtualenv --system-site-packages env/
-. env/bin/activate
-pip install -r requirements.txt
-```
-
-Then do `make html` like above.
-
-### Rebuilding automatically on changes
-
-To build the documentation every time you save your changes, install
-[watchexec](https://github.com/watchexec/watchexec) then run the following
-command in this directory:
-
-```sh
-watchexec make html
-```
+Here are some quick links to the areas you might be interested in:
 
+1. [Contributing to the online manual](https://docs.godotengine.org/en/latest/community/contributing/documentation_guidelines.html)
+2. [Contributing to the class reference](https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html)
+3. [Writing guidelines](https://docs.godotengine.org/en/latest/community/contributing/docs_writing_guidelines.html)
+4. [Translating the documentation](https://docs.godotengine.org/en/latest/community/contributing/editor_and_docs_localization.html)
+    
 ## License
 
 At the exception of the `classes/` folder, all the content of this repository is licensed under the Creative Commons Attribution 3.0 Unported license ([CC BY 3.0](https://creativecommons.org/licenses/by/3.0/)) and is to be attributed to "Juan Linietsky, Ariel Manzur and the Godot community".

community/contributing/building_the_manual.rst

@@ -0,0 +1,112 @@
+.. _doc_building_the_manual:
+
+Building the manual with Sphinx
+===============================
+
+This page explains how to build a local copy of the Godot manual using the
+Sphinx docs engine. This allows you to have local HTML files and build the
+documentation as a PDF, EPUB, or LaTeX file, for example.
+
+To get started, you need to install:
+
+1. `Sphinx <https://www.sphinx-doc.org/>`__
+2. To build the docs as HTML files, the `readthedocs.org theme
+   <https://github.com/snide/sphinx_rtd_theme>`__
+3. The Sphinx extensions defined in this repository's ``requirements.txt`` file
+
+We recommend using `pip <https://pip.pypa.io>` _, Python’s package manager to
+install all these tools. It comes pre-installed with `Python
+<https://www.python.org/>`__. Ensure that you install and use Python 3.
+
+.. code:: sh
+
+   pip install -r requirements.txt
+
+.. note:: On Linux distributions, you may need to write ``pip3`` instead of
+          ``pip`` because you generally have both Python 2 and 3 installed on
+          your system. Alternatively, you can explicitly ask Python 3 to execute
+          its version of pip as a module like so: ``python3 -m pip``.
+
+With the programs installed, you can build the HTML documentation from the root
+folder of this repository with the following command:
+
+.. code:: sh
+
+   make html
+
+If you run into errors, you may try the following command:
+
+.. code:: sh
+
+   make SPHINXBUILD=~/.local/bin/sphinx-build html
+
+Building the documentation requires at least 8 GB of RAM to run without disk
+swapping, which slows it down. If you have at least 16 GB of RAM, you can speed
+up compilation by running:
+
+.. code:: bash
+
+   # On Linux/macOS
+   make html SPHINXOPTS=-j2
+
+   # On Windows
+   set SPHINXOPTS=-j2 && make html
+
+The compilation will take some time as the ``classes/`` folder contains hundreds
+of files.
+
+You can then browse the documentation by opening ``_build/html/index.html`` in
+your web browser.
+
+In case you of a ``MemoryError`` or ``EOFError``, you can remove the
+``classes/`` folder and run ``make`` again. This will drop the class references
+from the final HTML documentation but will keep the rest intact.
+
+.. note:: If you delete the ``classes/`` folder, do not use ``git add .`` when
+          working on a pull request or the whole ``classes/`` folder will be
+          removed when you commit. See `#3157
+          <https://github.com/godotengine/godot-docs/issues/3157>`__ for more
+          detail.
+
+
+Building with Sphinx on Windows
+-------------------------------
+
+On Windows, you need to:
+
+1. Download the Python installer `here <https://www.python.org/downloads/>`__.
+2. Install Python. Be sure to check the “Add Python to PATH” checkbox.
+3. Use the above ``pip`` commands to install required programs.
+
+To build the documentation, open the root directory of this repository in your
+command line and execute ``make.bat`` like so:
+
+.. code:: sh
+
+   make.bat html
+
+Alternatively, you can build the documentation by running the sphinx-build
+program manually:
+
+.. code:: sh
+
+   sphinx-build -b html ./ _build
+
+Note that during the first build, various installation prompts may appear and
+ask to install LaTeX plugins. Make sure you don’t miss them, especially if they
+open behind other windows. The build may hang until you confirm these prompts.
+
+Building with Sphinx and virtualenv
+-----------------------------------
+
+If you want your Sphinx installation scoped to the project, you can install
+sphinx-build using virtualenv. To do so, run this command from this repository's
+root folder:
+
+.. code:: sh
+
+   virtualenv --system-site-packages env/
+   . env/bin/activate
+   pip install -r requirements.txt
+
+Then, run ``make html`` as shown above.

community/contributing/documentation_guidelines.rst

@@ -59,6 +59,84 @@ and to log in to use it. Once logged in, you can propose change like so:
 Another contributor will review your changes and merge them into the docs if
 they're good. They may also make changes or ask you to do so before merging.
 
+Contributing changes
+--------------------
+
+**Pull Requests should use the ``master`` branch by default. Only make
+Pull Requests against other branches (e.g. ``2.1`` or ``3.0``) if your
+changes only apply to that specific version of Godot.**
+
+Though arguably less convenient to edit than a wiki, this Git repository
+is meant to receive pull requests to always improve the documentation,
+add new pages, etc. Having direct access to the source files in a
+revision control system is a big plus to ensure the quality of our
+documentation.
+
+Editing existing pages
+~~~~~~~~~~~~~~~~~~~~~~
+
+To edit an existing page, locate its .rst source file and open it in
+your favorite text editor. You can then commit the changes, push them to
+your fork and make a pull request. **Note that the pages in ``classes/``
+should not be edited here, they are automatically generated from
+Godot’s**\ `XML class
+references <https://github.com/godotengine/godot/tree/master/doc/classes>`__\ **.**
+See `Contribute to the Class
+Reference <https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html>`__
+for details.
+
+Adding new pages
+~~~~~~~~~~~~~~~~
+
+To add a new page, create a .rst file with a meaningful name in the
+section you want to add a file to,
+e.g. \ ``tutorials/3d/light_baking.rst``. Write its content like you
+would do for any other file, and make sure to define a reference name
+for Sphinx at the beginning of the file (check other files for the
+syntax), based on the file name with a “doc\_” prefix
+(e.g. ``.. _doc_light_baking:``).
+
+You should then add your page to the relevant “toctree” (table of
+contents, e.g. \ ``tutorials/3d/index.rst``). By convention, the files
+used to define the various levels of toctree are prefixed with an
+underscore, so in the above example the file should be referenced in
+``tutorials/3d/_3d_graphics.rst``. Add your new filename to the list on
+a new line, using a relative path and no extension, e.g. here
+``light_baking``.
+
+Sphinx and reStructuredText syntax
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Check Sphinx’s `reST
+Primer <https://www.sphinx-doc.org/en/stable/rest.html>`__ and the
+`official reference <http://docutils.sourceforge.net/rst.html>`__ for
+details on the syntax.
+
+Sphinx uses specific reST comments to do specific operations, like
+defining the table of contents (``:toctree:``) or cross-referencing
+pages. Check the `official Sphinx
+documentation <https://www.sphinx-doc.org/en/stable/index.html>`__ for
+more details, or see how things are done in existing pages and adapt it
+to your needs.
+
+Adding images and attachments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To add images, please put them in an ``img/`` folder next to the .rst
+file with a meaningful name and include them in your page with:
+
+.. code:: rst
+
+   .. image:: img/image_name.png
+
+Similarly, you can include attachments (like assets as support material
+for a tutorial) by placing them into a ``files/`` folder next to the
+.rst file, and using this inline markup:
+
+.. code:: rst
+
+   :download:`myfilename.zip <files/myfilename.zip>`
+
 What is the Godot documentation
 -------------------------------
 

community/contributing/index.rst

@@ -17,3 +17,4 @@ Contributing
    updating_the_class_reference
    class_reference_writing_guidelines
    editor_and_docs_localization
+   building_the_manual