You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
20
+
All contributors are welcome to help on the Godot documentation.
21
21
22
-
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.
23
-
2. Before writing, be sure to check out our style guides:
-[GDScript style guide](https://docs.godotengine.org/en/latest/tutorials/scripting/gdscript/gdscript_styleguide.html) if you write GDScript code.
26
-
-[C# style guide](https://docs.godotengine.org/en/latest/tutorials/scripting/c_sharp/c_sharp_style_guide.html) if you write C# code.
22
+
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.
27
23
28
-
We also detail how to create new pages on the documentation [here](https://docs.godotengine.org/en/latest/community/contributing/documentation_guidelines.html).
29
-
30
-
**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.**
31
-
32
-
### Editing existing pages
33
-
34
-
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.
35
-
**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).**
36
-
See [Contribute to the Class Reference](https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html) for details.
37
-
38
-
### Adding new pages
39
-
40
-
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:`).
41
-
42
-
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`.
43
-
44
-
### Sphinx and reStructuredText syntax
45
-
46
-
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.
47
-
48
-
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.
49
-
50
-
### Adding images and attachments
51
-
52
-
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:
53
-
```rst
54
-
.. image:: img/image_name.png
55
-
```
56
-
57
-
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:
58
-
```rst
59
-
:download:`myfilename.zip <files/myfilename.zip>`
60
-
```
61
-
62
-
## Building with Sphinx
63
-
64
-
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).
65
-
You also need to install the Sphinx extensions defined in `requirements.txt`.
66
-
67
-
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:
68
-
69
-
```sh
70
-
pip install -r requirements.txt
71
-
```
72
-
73
-
You can then build the HTML documentation from the root folder of this repository with:
74
-
75
-
```sh
76
-
make html
77
-
```
78
-
79
-
or:
80
-
81
-
```sh
82
-
make SPHINXBUILD=~/.local/bin/sphinx-build html
83
-
```
84
-
85
-
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:
86
-
87
-
```bash
88
-
# On Linux/macOS
89
-
make html SPHINXOPTS=-j2
90
-
91
-
# On Windows
92
-
set SPHINXOPTS=-j2 && make html
93
-
```
94
-
95
-
The compilation might take some time as the `classes/` folder contains many files to parse.
96
-
97
-
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.
98
-
99
-
You can then test the changes live by opening `_build/html/index.html` in your favorite browser.
100
-
101
-
### Building with Sphinx on Windows
102
-
103
-
On Windows, you need to:
104
-
* Download the Python installer [here](https://www.python.org/downloads/).
105
-
* Install Python. Don't forget to check the "Add Python to PATH" box.
106
-
* Use the above `pip` commands.
107
-
108
-
Building is still done at the root folder of this repository using the provided `make.bat`:
109
-
```sh
110
-
make.bat html
111
-
```
112
-
113
-
Alternatively, you can build with this command instead:
114
-
```sh
115
-
sphinx-build -b html ./ _build
116
-
```
117
-
118
-
Note that during the first build, various installation prompts may appear and ask to install LaTeX plugins.
119
-
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.
120
-
121
-
You could also install a normal `make` toolchain (for example via MinGW) and build the docs using the normal `make html`.
122
-
123
-
### Building with Sphinx and virtualenv
124
-
125
-
If you want your Sphinx installation scoped to the project, you can install it using virtualenv.
126
-
Execute this from the root folder of this repository:
127
-
128
-
```sh
129
-
virtualenv --system-site-packages env/
130
-
. env/bin/activate
131
-
pip install -r requirements.txt
132
-
```
133
-
134
-
Then do `make html` like above.
135
-
136
-
### Rebuilding automatically on changes
137
-
138
-
To build the documentation every time you save your changes, install
139
-
[watchexec](https://github.com/watchexec/watchexec) then run the following
140
-
command in this directory:
141
-
142
-
```sh
143
-
watchexec make html
144
-
```
24
+
Here are some quick links to the areas you might be interested in:
145
25
26
+
1.[Contributing to the online manual](https://docs.godotengine.org/en/latest/community/contributing/contibuting_to_the_documentation.html)
27
+
2.[Contributing to the class reference](https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html)
5.[Translating the documentation](https://docs.godotengine.org/en/latest/community/contributing/editor_and_docs_localization.html)
31
+
146
32
## License
147
33
148
34
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 commit comments