mirror of
https://github.com/stan220/godot-docs.git
synced 2026-09-08 19:29:06 +00:00
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
This commit is contained in:
Nathan Lovato
@@ -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".
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
-------------------------------
|
||||
|
||||
|
||||
@@ -17,3 +17,4 @@ Contributing
|
||||
updating_the_class_reference
|
||||
class_reference_writing_guidelines
|
||||
editor_and_docs_localization
|
||||
building_the_manual
|
||||
|
||||
Reference in New Issue
Block a user