From f85fa7556141421953fca9e3fdc345dd33dee6e0 Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral <38422348+umarcor@users.noreply.github.com> Date: Tue, 18 Apr 2023 05:13:51 +0200 Subject: [PATCH] [contributing/documentation/building_the_manual] use tabs and admonitions (#7074) * [contributing/documentation/building_the_manual] use tabs and admonitions --------- Co-authored-by: Max Hilbrunner --- .../documentation/building_the_manual.rst | 142 ++++++++++++------ 1 file changed, 97 insertions(+), 45 deletions(-) diff --git a/contributing/documentation/building_the_manual.rst b/contributing/documentation/building_the_manual.rst index c2f15c6e1..68253eba0 100644 --- a/contributing/documentation/building_the_manual.rst +++ b/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. + +.. 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 `__ for more detail. + +.. _doc_building_the_manual:performance: + +Hints for performance +===================== + +RAM usage +--------- + +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: + +.. tabs:: + + .. group-tab:: Windows + + .. code:: pwsh + + set SPHINXOPTS=-j2 && make html + + .. group-tab:: Other platforms + + .. code:: sh + + make html SPHINXOPTS=-j2 + +Specifying a list of files +-------------------------- + +You can specify a list of files to build, which can greatly speed up compilation: .. code:: sh - # 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. - -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. - -.. 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 - `__ for more - detail. - -Alternatively, you can build the documentation by running the sphinx-build -program manually: - -.. code:: sh - - sphinx-build -b html ./ _build/html - -You can also 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