mirror of
https://github.com/godotengine/godot-docs.git
synced 2026-01-04 14:11:02 +03:00
[contributing/documentation/building_the_manual] use tabs and admonitions (#7074)
* [contributing/documentation/building_the_manual] use tabs and admonitions --------- Co-authored-by: Max Hilbrunner <mhilbrunner@users.noreply.github.com>
This commit is contained in:
Unai Martinez-Corral
committed by
GitHub
GitHub
parent
5593a181c5
commit
f85fa75561
@@ -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 <https://github.com/godotengine/godot-docs/issues/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
|
||||
<https://github.com/godotengine/godot-docs/issues/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
|
||||
|
||||
Reference in New Issue
Block a user