#godot #docs #howto

skyace65 010188a56a Replace images and move text for visual shader page 5 yıl önce
.github 41109cc583 PR template: Clarification 7 yıl önce
_static e23ee5b081 Fix typos with codespell 5 yıl önce
_templates 54c3b3e98a Adds a breadcrumb template to manage hiding 'Edit on Github' link. 6 yıl önce
about 4302dd2f37 Remove redundant adjective in introduction.rst 5 yıl önce
classes c3ccdd76ee Sync classref with current source 5 yıl önce
community e429494c0e Made "promotion" into an adjective 5 yıl önce
development fcac70e8a5 Windows: Mention requirement to use posix threads with MinGW 5 yıl önce
extensions 0d0f9961f4 fix build errors with `make latexpdf` 5 yıl önce
getting_started ed3e56fdd4 Fix some markup issues 5 yıl önce
img 5b2aaf8d41 Optimize PNGs with optipng 6 yıl önce
tutorials 010188a56a Replace images and move text for visual shader page 5 yıl önce
.gitignore e2cfe881e3 .gitignore improvements 6 yıl önce
.readthedocs.yml 370022acf4 RTD: Also disable PDF builds on each commits 7 yıl önce
LICENSE.txt 9bfc111547 Add full text of CC-BY-3.0 license 6 yıl önce
Makefile 309a4382c9 Default to parallel builds in Sphinx for faster builds 5 yıl önce
README.md d1a9f2e54f fix 2 dead links in README.md 5 yıl önce
conf.py 6b683b77ca Tweak the theme to better match Godot's visual identity 5 yıl önce
index.rst 209af20763 Describe the process of creating editor icons globally and per module 6 yıl önce
make.bat 309a4382c9 Default to parallel builds in Sphinx for faster builds 5 yıl önce

README.md

Godot Engine documentation

This repository contains the source files of Godot Engine's documentation, in reStructuredText markup language (reST).

They are meant to be parsed with the Sphinx documentation builder to build the HTML documentation on Godot's website.

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. See Contribute to the Class Reference 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 and the official reference 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 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:

.. 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:

: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 >= 1.3 as well as (for the HTML) the readthedocs.org theme. Only the Python 3 flavor was tested, though the Python 2 versions might work too.

Those tools are best installed using pip, Python's module installer. The Python 3 version might be provided (on Linux distros) as pip3 or python3-pip. You can then run:

pip3 install sphinx
pip3 install sphinx_rtd_theme

You can then build the HTML documentation from the root folder of this repository with:

make html

or:

make SPHINXBUILD=~/.local/bin/sphinx-build html

The compilation might take some time as the classes/ folder contains many files to parse. 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.
  • 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:

make.bat html

Alternatively, you can build with this command instead:

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:

virtualenv --system-site-packages env/
. env/bin/activate
pip3 install sphinx
pip3 install sphinx_rtd_theme

Then do make html like above.

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) and is to be attributed to "Juan Linietsky, Ariel Manzur and the Godot community". See LICENSE.txt for details.

The files in the classes/ folder are derived from Godot's main source repository and are distributed under the MIT license, with the same authors as above.