[contributing/documentation/building_the_manual] use tabs and admonitions (#7074)

* [contributing/documentation/building_the_manual] use tabs and admonitions

---------

Co-authored-by: Max Hilbrunner <[email protected]>

contributing/documentation/building_the_manual.rst

@@ -24,18 +24,51 @@ Before you get started, make sure that you have:
 
     a.  Create the virtual environment:
 
-        - On Windows, run ``py -m venv godot-docs-venv``
-        - On other platforms, run ``python3 -m venv godot-docs-venv``
+        .. tabs::
+
+            .. group-tab:: Windows
+
+                .. code:: pwsh
+
+                    py -m venv godot-docs-venv
+
+            .. group-tab:: Other platforms
+
+                .. code:: sh
+
+                    python3 -m venv godot-docs-venv
 
     b.  Activate the virtual environment:
 
-        - On Windows, run ``godot-docs-venv\Scripts\activate.bat``
-        - On other platforms, run ``source godot-docs-venv/bin/activate``
+        .. tabs::
+
+            .. group-tab:: Windows
+
+                .. code:: pwsh
+
+                    godot-docs-venv\Scripts\activate.bat
+
+            .. group-tab:: Other platforms
+
+                .. code:: sh
+
+                    source godot-docs-venv/bin/activate
 
     c.  *(Optional)* Update pre-installed packages:
 
-        - On Windows, run ``py -m pip install --upgrade pip setuptools``
-        - On other platforms, run ``pip3 install --upgrade pip setuptools``
+        .. tabs::
+
+            .. group-tab:: Windows
+
+                .. code:: pwsh
+
+                    py -m pip install --upgrade pip setuptools
+
+            .. group-tab:: Other platforms
+
+                .. code:: sh
+
+                    pip3 install --upgrade pip setuptools
 
 2.  Clone the docs repo:
 
@@ -61,8 +94,23 @@ Before you get started, make sure that you have:
 
         make html
 
-.. note:: On Windows, that command will run ``make.bat`` instead of GNU Make (or
-          an alternative).
+    .. note::
+        On Windows, that command will run ``make.bat`` instead of GNU Make (or an alternative).
+
+    Alternatively, you can build the documentation by running the sphinx-build program manually:
+
+    .. code:: sh
+
+        sphinx-build -b html ./ _build/html
+
+The compilation will take some time as the ``classes/`` folder contains hundreds of files.
+See :ref:`doc_building_the_manual:performance`.
+
+You can then browse the documentation by opening ``_build/html/index.html`` in
+your web browser.
+
+Dealing with errors
+===================
 
 If you run into errors, you may try the following command:
 
@@ -70,43 +118,47 @@ If you run into errors, you may try the following command:
 
     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:
+If you get 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.
 
-.. code:: sh
+.. important::
+    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.
 
-    # On Linux/macOS
-    make html SPHINXOPTS=-j2
+.. _doc_building_the_manual:performance:
 
-    # On Windows
-    set SPHINXOPTS=-j2 && make html
+Hints for performance
+=====================
 
-The compilation will take some time as the ``classes/`` folder contains hundreds
-of files.
+RAM usage
+---------
 
-You can then browse the documentation by opening ``_build/html/index.html`` in
-your web browser.
+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:
 
-If you get 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.
+.. tabs::
 
-.. 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.
+    .. group-tab:: Windows
 
-Alternatively, you can build the documentation by running the sphinx-build
-program manually:
+        .. code:: pwsh
 
-.. code:: sh
+            set SPHINXOPTS=-j2 && make html
+
+    .. group-tab:: Other platforms
+
+        .. code:: sh
+
+            make html SPHINXOPTS=-j2
 
-   sphinx-build -b html ./ _build/html
+Specifying a list of files
+--------------------------
 
-You can also specify a list of files to build, which can greatly speed up compilation:
+You can specify a list of files to build, which can greatly speed up compilation:
 
 .. code:: sh
 
-  sphinx-build -b html ./ _build/html classes/class_node.rst classes/class_resource.rst
+    make FILELIST='classes/class_node.rst classes/class_resource.rst' html