diff --git a/README.md b/README.md index 2bb6448a8..d1ba68ff1 100644 --- a/README.md +++ b/README.md @@ -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 ` -``` - -## 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". diff --git a/community/contributing/building_the_manual.rst b/community/contributing/building_the_manual.rst new file mode 100644 index 000000000..b1f11b572 --- /dev/null +++ b/community/contributing/building_the_manual.rst @@ -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 `__ +2. To build the docs as HTML files, the `readthedocs.org theme + `__ +3. The Sphinx extensions defined in this repository's ``requirements.txt`` file + +We recommend using `pip ` _, Python’s package manager to +install all these tools. It comes pre-installed with `Python +`__. 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 + `__ for more + detail. + + +Building with Sphinx on Windows +------------------------------- + +On Windows, you need to: + +1. Download the Python installer `here `__. +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. diff --git a/community/contributing/documentation_guidelines.rst b/community/contributing/documentation_guidelines.rst index af16d82a5..2ebc0a3f3 100644 --- a/community/contributing/documentation_guidelines.rst +++ b/community/contributing/documentation_guidelines.rst @@ -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 `__\ **.** +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: + +.. 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 ` + What is the Godot documentation ------------------------------- diff --git a/community/contributing/index.rst b/community/contributing/index.rst index 4c74348b5..02a84776d 100644 --- a/community/contributing/index.rst +++ b/community/contributing/index.rst @@ -17,3 +17,4 @@ Contributing updating_the_class_reference class_reference_writing_guidelines editor_and_docs_localization + building_the_manual