From c01a71d691bc915488270744830d717beeb86ed9 Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Thu, 24 Sep 2020 19:10:20 -0600 Subject: [PATCH 01/10] Edit documentation_guidelines.rst - Start with a short sentence describing the doc's content - Link to the translation docs - Remove section about translation - Many wording edits --- .../contributing/documentation_guidelines.rst | 133 ++++++++---------- 1 file changed, 57 insertions(+), 76 deletions(-) diff --git a/community/contributing/documentation_guidelines.rst b/community/contributing/documentation_guidelines.rst index faaafe42d..0713e9b3c 100644 --- a/community/contributing/documentation_guidelines.rst +++ b/community/contributing/documentation_guidelines.rst @@ -1,88 +1,85 @@ .. _doc_documentation_guidelines: -Documentation guidelines -======================== +Contributing to the documentation +================================= -This page describes the rules to follow if you want to contribute to Godot -Engine by writing or reviewing documentation, or by translating existing -documentation. Also, have a look at README of the -`godot-docs GitHub repository `_ -and the `docs front page `_ -on what steps to follow and how to contact the docs team. +This guide explains how to contribute to Godot's documentation, be it by +writing, reviewing, or translating pages. + +.. seealso:: + + If you want to translate pages or the class reference from English to other + languages, read :ref:`doc_editor_and_docs_localization`. + +Getting started +--------------- + +To modify or create pages in the reference manual, you need to edit ``.rst`` +files in the `godot-docs GitHub repository +`_. Modifying those pages in a pull +request and triggers a rebuild of the online documentation upon merging. -How to contribute ------------------ -Creating or modifying documentation pages is mainly done via the -`godot-docs GitHub repository `_. -The HTML (or PDF and EPUB) documentation is generated from the .rst files -(reStructuredText markup language) in that repository. Modifying those pages -in a pull request and getting it merged will trigger a rebuild of the online -documentation. .. seealso:: For details on Git usage and the pull request workflow, please - refer to the :ref:`doc_pr_workflow` page. Most of what it - describes regarding the main godotengine/godot repository is - also valid for the docs repository. + refer to the :ref:`doc_pr_workflow` page. Most of what it describes + regarding the main godotengine/godot repository is also valid for + the docs repository. -The README.md file contains all the information you need to get you started, -please read it. In particular, it contains some tips and tricks and links to -reference documentation about the reStructuredText markup language. +.. warning:: The class reference's source files are in the :ref:`Godot engine + repository `. We generate the + :ref:`Godot API ` section of this documentation from them. + If you want to update the description of a class, its methods, or + properties, read :ref:`doc_updating_the_class_reference`. -.. warning:: If you want to edit the **API reference**, please note that it - should *not* be done in the godot-docs repository. Instead, you - should edit the ``doc/classes/*`` XML files of Godot's - main repository. These files are then later used to generate the - in-editor documentation as well as the API reference of the - online docs. Read more here: :ref:`doc_updating_the_class_reference`. +Editing pages online +-------------------- -The 'Edit on GitHub' link -------------------------- +You can edit the documentation online by clicking the **Edit on GitHub** link in +the top-right of every page. -If you're reading documentation on `docs.godotengine.org `_, -you'll see an **Edit on GitHub** hyperlink at the top right of the page. -Once you've created a GitHub account, you can propose changes to a page you're -reading as follows: +Doing so takes you to the GitHub text editor. You need to have a GitHub account +and to log in to use it. Once logged in, you can propose change like so: 1. Click the **Edit on GitHub** button. 2. On the GitHub page you're taken to, click the pencil icon in the top-right - corner near the **Raw**, **Blame** and **History** buttons. It has the tooltip - "Edit the file in a fork of this project". + corner near the **Raw**, **Blame**, and **History** buttons. It has the + tooltip "Edit the file in a fork of this project". -3. Complete all the edits you want to make for that page. +3. Edit the text in the text editor. -4. Summarize the changes you made in the form at the bottom of the page and - click the button labelled **Propose file change** when done. +4. At the bottom of the web page, summarize the changes you made and click the + button **Propose file change**. 5. On the following screens, click the **Create pull request** button until you - see a message like *Username wants to merge 1 commit into - godotengine:master from Username:patch-6*. + see a message like *Username wants to merge 1 commit into godotengine:master + from Username:patch-6*. -6. A reviewer will evaluate your changes and incorporate them into the docs if - they're acceptable. You might also be asked to make - modifications to your changes before they're included. +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. -What makes good documentation? ------------------------------- +What is the Godot documentation +------------------------------- -Documentation should be well written in plain English, using well-formed -sentences and various levels of sections and subsections. It should be clear -and objective. Also, have a look at the :ref:`doc_docs_writing_guidelines`. +The Godot documentation is intended as a comprehensive reference manual for the +Godot game engine. It is not meant to contain step-by-step tutorials, with the +exception of two game creation tutorials in the Getting Started section. -We differentiate tutorial pages from other documentation pages by these -definitions: +We strive to write objective content in accessible and well-written English. To +contribute, you should also read: -- Tutorial: a page aiming at explaining how to use one or more concepts in - the editor or scripts in order to achieve a specific goal with a learning - purpose (e.g. "Making a simple 2d Pong game", "Applying forces to an - object"). -- Documentation: a page describing precisely one and only one concept at a - time, if possible exhaustively (e.g. the list of methods of the - Sprite class, or an overview of the input management in Godot). +- The :ref:`doc_docs_writing_guidelines`. There, you will find rules to write -You are free to write the kind of documentation you wish, as long as you -respect the following rules (and the ones on the repo). +- Tutorial: a page aiming at explaining how to use one or more concepts in the + editor or scripts in order to achieve a specific goal with a learning purpose + (e.g. "Making a simple 2d Pong game", "Applying forces to an object"). +- Documentation: a page describing precisely one and only one concept at a time, + if possible exhaustively (e.g. the list of methods of the Sprite class, or an + overview of the input management in Godot). + +You are free to write the kind of documentation you wish, as long as you respect +the following rules (and the ones on the repo). Titles ------ @@ -113,22 +110,6 @@ And this is a bad example: Only project, people and node class names should have capitalized first letter. -Translating existing pages --------------------------- - -You can help to translate the official Godot documentation on our `Hosted Weblate `_. - -.. image:: https://hosted.weblate.org/widgets/godot-engine/-/godot-docs/287x66-white.png - :alt: Translation state - :align: center - :target: https://hosted.weblate.org/engage/godot-engine/?utm_source=widget - :width: 287 - :height: 66 - -There also is the official -`Godot i18n repository `_ -where you can see when the data was last synchronized. - License ------- From 4084edf0e4e1e7ba628f29fb0255a85f45648e4a Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Thu, 24 Sep 2020 19:12:16 -0600 Subject: [PATCH 02/10] Edit updating_the_class_reference.rst, split into two pages - Wording updates - Separate writing guidelines for the class ref and git PR guide into - two pages --- .../class_reference_writing_guidelines.rst | 181 ++++++++ community/contributing/index.rst | 1 + .../updating_the_class_reference.rst | 410 ++++++------------ 3 files changed, 310 insertions(+), 282 deletions(-) create mode 100644 community/contributing/class_reference_writing_guidelines.rst diff --git a/community/contributing/class_reference_writing_guidelines.rst b/community/contributing/class_reference_writing_guidelines.rst new file mode 100644 index 000000000..68114481f --- /dev/null +++ b/community/contributing/class_reference_writing_guidelines.rst @@ -0,0 +1,181 @@ +.. _doc_class_reference_writing_guidelines: + +Class reference writing guidelines +================================== + +This page explains how to write the class reference. You will learn where to +write new descriptions for the classes, methods, and properties for Godot's +built-in node types. + +.. seealso:: + + To learn to submit your changes to the Godot project using the Git version + control system, see :ref:`doc_updating_the_class_reference`. + +Each class's reference is contained in an XML file like the one below: + +.. code-block:: xml + + + + Base node for 2D system. + + + Base node for 2D system. Node2D contains a position, rotation and scale, which is used to position and animate. It can alternatively be used with a custom 2D transform ([Matrix32]). A tree of Node2Ds allows complex hierarchies for animation and positioning. + + + + + + + Sets the position of the 2D node. + + + [...] + + + + + + + + + + + [...] + + + + + + + + +It starts with brief and long descriptions. In the generated docs, the brief +description is always at the top of the page, while the long description lies +below the list of methods, variables, and constants. You can find methods, +member variables, constants, and signals in separate XML nodes. For each, learn +how they work in Godot's source code, and fill their tag. + +Our job is to complete or improve the text in these tags: + +- +- +- +- +- +- + +Write in a clear and simple language. Always follow the :ref:`writing guidelines +` to keep your descriptions short and easy to read. +**Do not leave empty lines** in the descriptions: each line in the XML file will +result in a new paragraph, even if it is empty. + +How to edit class XML +--------------------- + +Edit the file for your chosen class in ``doc/classes/`` to update the class +reference. The folder contains an XML file for each class. The XML lists the +constants and methods you will find in the class reference. Godot generates and +updates the XML automatically. + +Edit it using your favorite text editor. If you use a code editor, make sure +that it doesn't change the indent style: you should use tabs for the XML, and +four spaces inside BBCode-style blocks. More on that below. + +To check that the modifications you've made are correct in the +generated documentation, you need to build Godot. To learn how, read the +:ref:`compilation guide `. Then, run the editor and open +the help for the page you modified. + +We recommend using a code editor that supports XML files like Vim, Atom, Code, +Notepad++, or another to comfortably edit the file. You can also use their +search feature to find classes and properties quickly. + +.. _doc_updating_the_class_reference_bbcode: + +Improve formatting with BBCode style tags +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Godot's class reference supports BBCode-like tags. They add nice formatting to +the text. Here's the list of available tags: + ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +| Tag | Effect | Usage | Result | ++===========================+================================+===================================+===================================================+ +| [Class] | Link a class | Move the [Sprite]. | Move the :ref:`class_sprite`. | ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +| [method methodname] | Link to a method in this class | Call [method hide]. | See :ref:`hide `. | ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +| [method Class.methodname] | Link to another class's method | Call [method Spatial.hide]. | See :ref:`hide `. | ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +| [member membername] | Link to a member in this class | Get [member scale]. | Get :ref:`scale `. | ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +| [member Class.membername] | Link to another class's member | Get [member Node2D.scale]. | Get :ref:`scale `. | ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +| [signal signalname] | Link to a signal in this class | Emit [signal renamed]. | Emit :ref:`renamed `. | ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +| [signal Class.signalname] | Link to another class's signal | Emit [signal Node.renamed]. | Emit :ref:`renamed `. | ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +| [b] [/b] | Bold | Some [b]bold[/b] text. | Some **bold** text. | ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +| [i] [/i] | Italic | Some [i]italic[/i] text. | Some *italic* text. | ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +| [code] [/code] | Monospace | Some [code]monospace[/code] text. | Some ``monospace`` text. | ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +| [kbd] [/kbd] | Keyboard/mouse shortcut | Some [kbd]Ctrl + C[/kbd] key. | Some :kbd:`Ctrl + C` key. | ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +| [codeblock] [/codeblock] | Multiline preformatted block | *See below.* | *See below.* | ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ + +Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``, +always use **four spaces** for indentation. The parser will delete tabs. For +example: + +.. code-block:: none + + [codeblock] func _ready(): var sprite = get_node("Sprite") + print(sprite.get_pos()) [/codeblock] + +Will display as: + +.. code-block:: gdscript + + func _ready(): var sprite = get_node("Sprite") print(sprite.get_pos()) + +To denote important information, add a paragraph starting with "[b]Note:[/b]" at +the end of the description: + +.. code-block:: none + + [b]Note:[/b] Only available when using the Vulkan renderer. + +To denote crucial information that could cause security issues or loss of data +if not followed carefully, add a paragraph starting with "[b]Warning:[/b]" at +the end of the description: + +.. code-block:: none + + [b]Warning:[/b] If this property is set to [code]true[/code], it allows + clients to execute arbitrary code on the server. + +For deprecated properties, add a paragraph starting with "[i]Deprecated.[/i]". +Notice the use of italics instead of bold: + +.. code-block:: none + + [i]Deprecated.[/i] This property has been replaced by [member + other_property]. + +In all the paragraphs described above, make sure the punctuation is part of the +BBCode tags for consistency. + +I don't know what this method does! +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +No problem. Leave it behind, and list the methods you skipped when you request a +pull of your changes. Another writer will take care of it. + +You can still look at the methods' implementation in Godot's source code on +GitHub. If you have doubts, feel free to ask on the `Q&A website +`__ and IRC (Freenode, #godotengine). diff --git a/community/contributing/index.rst b/community/contributing/index.rst index c9e6cce8a..4c74348b5 100644 --- a/community/contributing/index.rst +++ b/community/contributing/index.rst @@ -15,4 +15,5 @@ Contributing documentation_guidelines docs_writing_guidelines updating_the_class_reference + class_reference_writing_guidelines editor_and_docs_localization diff --git a/community/contributing/updating_the_class_reference.rst b/community/contributing/updating_the_class_reference.rst index 34deee108..cce6c1d84 100644 --- a/community/contributing/updating_the_class_reference.rst +++ b/community/contributing/updating_the_class_reference.rst @@ -1,57 +1,85 @@ .. _doc_updating_the_class_reference: -Contributing to the class reference -=================================== +Contributing to the class reference with Git +============================================ .. highlight:: shell -.. note:: This guide also is available as a `video tutorial on YouTube `_. +This page gives you an overview of the steps to submit changes to Godot's class +reference using the Git version control system. -Godot ships with many nodes and singletons to help you develop your games. Each is a class, documented in the :ref:`class reference `. -This reference is essential for anyone learning the engine: it is available both online and in the engine. - -But it's incomplete. Some methods, variables and signals lack descriptions. Others changed with recent releases and need updates. -The developers can't write the entire reference on their own. Godot needs you, and all of us, to contribute. - -**Important:** If you are planning to make larger changes or a more substantial contribution, it is usually a good idea -to create an issue (or a comment in an existing one) to let others know so they don't start working on the same thing too. Class -reference issues should be opened in the `godot-docs repository `__. +The class reference is available online in the :ref:`classes ` +section of the documentation and in the Godot editor, from the help menu. .. seealso:: - Not sure where to start contributing? Take a look at the current class reference + This guide focuses on using Git. You can find the writing guidelines for the + class reference :ref:`here `. + + If you want to translate the class reference from English to another + language, see :ref:`doc_editor_and_docs_localization`. + +In the class reference, some methods, variables, and signals lack descriptions. +Others changed with recent releases and need updates. The developers can't write +the entire reference on their own. Godot needs you, and all of us, to +contribute. + +**Important:** If you plan to make large changes, you should create an issue on + the `godot-docs repository `_ + or comment on an existing issue. Doing so lets others know you're already + taking care of a given class. + +.. seealso:: + + Not sure which class to contribute to? Take a look at the class reference's completion status `here `__. How to contribute ----------------- -The class reference lies in the following XML files, in Godot's GitHub repository: `doc/classes/ `_. +You can find the source files for the class reference in Godot's GitHub +repository: `doc/classes/ +`_. -There are 5 steps to update the class reference (full guide below): +There are five steps to update the class reference: 1. Fork `Godot's repository `_ -2. Clone your fork on your computer -3. Edit the class file in ``doc/classes/`` to write documentation -4. Commit your changes and push them to your fork -5. Make a pull request on the Godot repository +2. Clone your fork on your computer. +3. Edit the class file in ``doc/classes/`` to write documentation. +4. Commit your changes and push them to your fork. +5. Make a pull request on the Godot repository. -.. warning:: Always use these XML files to edit the API reference. Do not edit the generated .rst files :ref:`in the online documentation `, hosted in the `godot-docs `_ repository. +You will find a complete breakdown of these steps below. -Get started with GitHub ------------------------ +.. seealso:: This guide is also available as a `video tutorial on YouTube + `_. -If you're new to Git and GitHub, this guide will help you get started. You'll learn to: +.. warning:: Always edit the API reference through these source XML files. Do + not edit the generated .rst files :ref:`in the online documentation + `, hosted in the `godot-docs + `_ repository. + +Getting started with GitHub +--------------------------- + +If you're new to using GitHub, the platform we use to develop Godot, this guide +will help you get started. You will learn to: - Fork and clone Godot's repository - Keep your fork up to date with other contributors -- Create a pull request so your improvements end in the official docs +- Create a pull request to submit your improvements to the official docs -.. note:: If you're new to Git, the version control system Godot uses, go through `GitHub's interactive guide `_. You'll learn some essential vocabulary and get a sense for the tool. +.. note:: If you're new to Git, the version control system Godot uses, start + with `GitHub's interactive guide + `_. You'll learn some + essential vocabulary and get a sense for how the tool works. -Fork Godot -~~~~~~~~~~ +Forking Godot +~~~~~~~~~~~~~ -Fork the Godot Engine into a GitHub repository of your own. +Start by forking the Godot Engine into a GitHub repository of your own. Read the +`GitHub forking guide `_ to learn +to create forks. Clone the repository on your computer: @@ -59,68 +87,116 @@ Clone the repository on your computer: git clone https://github.com/your_name/godot.git -Create a new branch to make your changes. It makes it a lot easier to sync your improvements with other docs writers. It's also easier to clean up your repository if you run into any issues with Git. +Create a new branch to make your changes. It makes it a lot easier to +synchronize your improvements with other contributors. It's also easier to clean +up your repository if you run into any issues with Git. :: git checkout -b your-new-branch-name -The new branch is the same as your master branch until you start to write API docs. In the ``doc/`` folder, you'll find the class reference. +The new branch is the same as your master branch until you start to write API +docs. In the ``doc/`` folder, you will find the class reference. -How to keep your local clone up-to-date -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Keeping your local clone up-to-date +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Other writers contribute to Godot's documentation. Your local repository will fall behind it, and you'll have to synchronize it. Especially if other contributors update the class reference while you work on it. +Other writers contribute to Godot's documentation. Your local repository will +fall behind it. You will have to synchronize it, especially if other +contributors update the class reference while working on it. -First add an ``upstream`` git *remote* to work with. Remotes are links to online repositories you can download new files from. +First, add an ``upstream`` Git *remote*. Remotes are links to online repositories +from which you can download new files. The following command registers a new +remote named "upstream" that links to the original Godot repository. :: git remote add upstream https://github.com/godotengine/godot -You can check the list of all remote servers with: +You can check the list of all remote servers with this command: :: git remote -v -You should have two: ``origin``, your fork on GitHub that Git adds by default, and ``upstream``, that you just added: +You should have two remotes: +1. ``origin``, corresponding to your fork on GitHub. Git adds it by default when + you clone a repository. +2. ``upstream``, that you just added. + +The output should look like the following: :: - origin https://github.com/your_name/godot.git (fetch) - origin https://github.com/your_name/godot.git (push) - upstream https://github.com/godotengine/godot.git (fetch) - upstream https://github.com/godotengine/godot.git (push) + origin https://github.com/your_name/godot.git (fetch) origin + https://github.com/your_name/godot.git (push) upstream + https://github.com/godotengine/godot.git (fetch) upstream + https://github.com/godotengine/godot.git (push) -Each time you want to sync your branch to the state of the upstream repository, enter: +Each time you want to synchronize your branch with the upstream repository, +enter: :: git pull --rebase upstream master -This command will first ``fetch``, or download the latest version of the Godot repository. Then, it will reapply your local changes on top. +This command will first ``fetch``, that is, download the latest version of the +Godot repository. Then, it will reapply your local changes on top of it. -If you made changes you don't want to keep in your local branch, use the following commands instead: +If you made changes you don't want to keep in your local branch, use the +following commands instead: :: - git fetch upstream - git reset --hard upstream master + git fetch upstream git reset --hard upstream master -**Warning:** The above command will reset your branch to the state of the ``upstream master`` branch. It will discard all local changes. Make sure to only run this *before* you make important changes. +**Warning:** The above command will reset your branch to the state of the + ``upstream master`` branch. It will discard all local changes. Make sure to + only run this *before* you make important changes. -Another option is to delete the branch you're working on, synchronize the master branch with the Godot repository, and create a new branch: +Another option is to delete the branch you're working on, synchronize the master +branch with the Godot repository, and create a new branch: :: - git checkout master - git branch -d your-new-branch-name - git pull --rebase upstream master - git checkout -b your-new-branch-name + git checkout master git branch -d your-new-branch-name git pull --rebase + upstream master git checkout -b your-new-branch-name -If you're feeling lost by now, come to our `IRC channels `_ and ask for help. Experienced Git users will give you a hand. +If you're feeling lost by now, come to our `IRC channels +`_ and ask for help. +Experienced Git users will give you a hand. + +Submitting your changes +~~~~~~~~~~~~~~~~~~~~~~~ + +Once you finished modifying the reference, push your changes to your GitHub +repository: + +:: + + git add doc/classes/.xml + git commit -m "Explain your modifications." + git push + +When it's done, you can ask for a pull request (abbreviated PR) on GitHub. + +To learn to create a pull request, read `Creating a pull request +`_ +in the GitHub documentation. + +.. warning:: + + You should avoid editing files directly on GitHub in the godot engine + repository. As hundreds of contributors work on the engine, the Git history + must stay clean. Each commit should bundle all related improvements you make + to the class reference. + + Editing from GitHub creates a new branch and Pull Request every time you + save your changes. Suppose days pass before your changes get a review. In + that case, you won't be able to update to the latest version of the + repository cleanly. Also, it's harder to keep clean indents with GitHub's + text editor. And they're essential in the class reference. Updating the documentation template ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -141,233 +217,3 @@ The XML files in doc/classes should then be up-to-date with current Godot Engine You are now ready to edit this file to add stuff. **Note:** If this has been done recently by another contributor, you don't forcefully need to go through these steps (unless you know that the class you plan to edit *has* been modified recently). - -Push and request a pull of your changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Once your modifications are finished, push your changes on your GitHub -repository: - -:: - - git add doc/classes/.xml - git commit -m "Explain your modifications." - git push - -When it's done, you can ask for a Pull Request via the GitHub UI of your Godot fork. - -.. warning:: - - Although you can edit files on GitHub, it's not recommended. As hundreds of contributors work on Godot, the Git history must stay clean. Each commit should bundle all related improvements you make to the class reference, a new feature, bug fixes... When you edit from GitHub, it will create a new branch and a Pull Request every time you want to save it. If a few days pass before your changes get a review, you won't be able to update to the latest version of the repository cleanly. Also, it's harder to keep clean indents from GitHub. And they're very important in the docs. - - TL;DR: If you don't know exactly what you're doing, do not edit files from GitHub. - -How to edit class XML ---------------------- - -Edit the file for your chosen class in ``doc/classes/`` to update the class reference. The folder contains an XML file for each class. The XML lists the constants and methods you'll find in the class reference. Godot generates and updates the XML automatically. - -Edit it using your favorite text editor. If you use a code editor, make sure that it doesn't change the indent style: tabs for the XML, and 4 spaces inside BBCode-style blocks. More on that below. - -If you need to check that the modifications you've made are correct in the generated documentation, build Godot as described :ref:`here `, run the editor and open the help for the page you modified. - -How to write the class reference -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Each class has a brief and long description. The brief description is always at the top of the page, while the full description lies below the list of methods, variables, and constants. Methods, member variables, constants, and signals are in separate categories or XML nodes. For each, learn how they work in Godot's source code, and fill their . - -Our job is to add the missing text between these marks: - -- -- -- -- -- -- - -Write using clear and simple language. Always follow the :ref:`writing guidelines ` to keep your descriptions short and easy to read. **Do not leave empty lines** in the descriptions: each line in the XML file will result in a new paragraph. - -Here's how a class looks like in XML: - -.. code-block:: xml - - - - Base node for 2D system. - - - Base node for the 2D system. Node2D contains a position, rotation, and scale, which is used to position and animate. It can alternatively be used with a custom 2D transform ([Matrix32]). A tree of Node2Ds allows complex hierarchies for animation and positioning. - - - - - - - Sets the position of the 2D node. - - - [...] - - - - - - - - - - - [...] - - - - - - - - -Use a code editor like Vim, Atom, Code, Notepad++ or anything similar to edit the file quickly. Use the search function to find classes fast. - -.. _doc_updating_the_class_reference_bbcode: - -Improve formatting with BBCode style tags -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Godot's class reference supports BBCode-like tags. They add nice formatting to the text. Here's the list of available tags: - -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| Tag | Effect | Usage | Result | -+============================+======================================+===================================+===================================================+ -| [Class] | Link a class | Move the [Sprite]. | Move the :ref:`class_sprite`. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [method methodname] | Link to a method in this class | Call [method hide]. | See :ref:`hide `. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [method Class.methodname] | Link to another class's method | Call [method Spatial.hide]. | See :ref:`hide `. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [member membername] | Link to a member in this class | Get [member scale]. | Get :ref:`scale `. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [member Class.membername] | Link to another class's member | Get [member Node2D.scale]. | Get :ref:`scale `. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [signal signalname] | Link to a signal in this class | Emit [signal renamed]. | Emit :ref:`renamed `. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [signal Class.signalname] | Link to another class's signal | Emit [signal Node.renamed]. | Emit :ref:`renamed `. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [b] [/b] | Bold | Some [b]bold[/b] text. | Some **bold** text. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [i] [/i] | Italic | Some [i]italic[/i] text. | Some *italic* text. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [code] [/code] | Monospace | Some [code]monospace[/code] text. | Some ``monospace`` text. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [kbd] [/kbd] | Keyboard/mouse shortcut | Some [kbd]Ctrl + C[/kbd] key. | Some :kbd:`Ctrl + C` key. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [codeblock] [/codeblock] | Multiline preformatted block | *See below.* | *See below.* | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [codeblocks] [/codeblocks] | [codeblock] for multiple languages | *See below.* | *See below.* | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [gdscript] [/gdscript] | GDScript codeblock tab in codeblocks | *See below.* | *See below.* | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [csharp] [/csharp] | C# codeblock tab in codeblocks | *See below.* | *See below.* | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ - -Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``, always use **four spaces** for indentation (the parser will delete tabs). Example: - -.. code-block:: none - - [codeblock] - func _ready(): - var sprite = get_node("Sprite") - print(sprite.get_pos()) - [/codeblock] - -Will display as: - -.. code-block:: gdscript - - func _ready(): - var sprite = get_node("Sprite") - print(sprite.get_pos()) - -If you need to have different code version in GDScript and C#, use ``[codeblocks]`` instead. If you use ``[codeblocks]``, you also need to have at least one of the language specific tags (``[gdscript]`` and ``[csharp]``). Always write GDScript code examples first! You can use this `experimental code translation tool `_ to speed up your workflow. - -.. code-block:: none - - [codeblocks] - [gdscript] - func _ready(): - var sprite = get_node("Sprite") - print(sprite.get_pos()) - [/gdscript] - [csharp] - public override void _Ready() - { - var sprite = GetNode("Sprite"); - GD.Print(sprite.GetPos()); - } - [/csharp] - [/codeblocks] - -Will display as: - -.. tabs:: - .. code-tab:: gdscript GDScript - - func _ready(): - var sprite = get_node("Sprite") - print(sprite.get_pos()) - - .. code-tab:: csharp - - public override void _Ready() - { - var sprite = GetNode("Sprite"); - GD.Print(sprite.GetPos()); - } - - -To denote important information, add a paragraph starting with "[b]Note:[/b]" at -the end of the description: - -.. code-block:: none - - [b]Note:[/b] Only available when using the Vulkan renderer. - -To denote crucial information that could cause security issues or loss of data -if not followed carefully, add a paragraph starting with "[b]Warning:[/b]" at the -end of the description: - -.. code-block:: none - - [b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server. - -For deprecated properties, add a paragraph starting with "[i]Deprecated.[/i]". -Notice the use of italics instead of bold: - -.. code-block:: none - - [i]Deprecated.[/i] This property has been replaced by [member other_property]. - -In all the paragraphs described above, make sure the punctuation is part of the -BBCode tags for consistency. - -I don't know what this method does! -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -No problem. Leave it behind and list the methods you skipped when you request a pull of your changes. Another writer will take care of it. - -You can still have a look at the methods' implementation in Godot's source code on GitHub. Also, if you have doubts, feel free to ask on the `Q&A website `__ and on IRC (freenode, #godotengine). - - -Localization -~~~~~~~~~~~~ - -The documentation can be translated in any language on `Hosted Weblate -`__. - -Translated strings are synced manually by documentation maintainers in -the `godot-docs-l10n `__ -repository. - -Languages with a good level of completion have their own localized -instances of ReadTheDocs. Open an issue on the ``godot-docs-l10n`` -repository if you think that a new language is complete enough to get -its own instance. From 503eb106193ab134ddd12c7f2e34a4c0a20f51e9 Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Thu, 24 Sep 2020 19:45:29 -0600 Subject: [PATCH 03/10] Fix links causing errors in documentation_guidelines --- community/contributing/documentation_guidelines.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/community/contributing/documentation_guidelines.rst b/community/contributing/documentation_guidelines.rst index 0713e9b3c..af16d82a5 100644 --- a/community/contributing/documentation_guidelines.rst +++ b/community/contributing/documentation_guidelines.rst @@ -26,11 +26,11 @@ request and triggers a rebuild of the online documentation upon merging. regarding the main godotengine/godot repository is also valid for the docs repository. -.. warning:: The class reference's source files are in the :ref:`Godot engine - repository `. We generate the - :ref:`Godot API ` section of this documentation from them. - If you want to update the description of a class, its methods, or - properties, read :ref:`doc_updating_the_class_reference`. +.. warning:: The class reference's source files are in the `Godot engine repository + `_. We generate the :ref:`Godot API + ` section of this documentation from them. If you want to update the + description of a class, its methods, or properties, read + :ref:`doc_updating_the_class_reference`. Editing pages online -------------------- From d74261bfb5f083a774e336828e7a09059cb76dd4 Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Thu, 24 Sep 2020 22:06:53 -0600 Subject: [PATCH 04/10] 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 --- README.md | 133 ++---------------- .../contributing/building_the_manual.rst | 112 +++++++++++++++ .../contributing/documentation_guidelines.rst | 78 ++++++++++ community/contributing/index.rst | 1 + 4 files changed, 200 insertions(+), 124 deletions(-) create mode 100644 community/contributing/building_the_manual.rst 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 From 1c648119d3dc42448fd632b8f62eb607b02461f3 Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Fri, 25 Sep 2020 08:23:49 -0600 Subject: [PATCH 05/10] Reorder and edit the documentation guidelines --- .../contributing/documentation_guidelines.rst | 213 ++++++++---------- 1 file changed, 98 insertions(+), 115 deletions(-) diff --git a/community/contributing/documentation_guidelines.rst b/community/contributing/documentation_guidelines.rst index 2ebc0a3f3..330898c1e 100644 --- a/community/contributing/documentation_guidelines.rst +++ b/community/contributing/documentation_guidelines.rst @@ -4,7 +4,7 @@ Contributing to the documentation ================================= This guide explains how to contribute to Godot's documentation, be it by -writing, reviewing, or translating pages. +writing or reviewing pages. .. seealso:: @@ -19,19 +19,56 @@ files in the `godot-docs GitHub repository `_. Modifying those pages in a pull request and triggers a rebuild of the online documentation upon merging. - - .. seealso:: For details on Git usage and the pull request workflow, please refer to the :ref:`doc_pr_workflow` page. Most of what it describes regarding the main godotengine/godot repository is also valid for the docs repository. -.. warning:: The class reference's source files are in the `Godot engine repository - `_. We generate the :ref:`Godot API - ` section of this documentation from them. If you want to update the - description of a class, its methods, or properties, read +.. warning:: The class reference's source files are in the `Godot engine + repository `_. We generate + the :ref:`Godot API ` section of this documentation + from them. If you want to update the description of a class, its + methods, or properties, read :ref:`doc_updating_the_class_reference`. +What is the Godot documentation +------------------------------- + +The Godot documentation is intended as a comprehensive reference manual for the +Godot game engine. It is not meant to contain step-by-step tutorials, except for +two game creation tutorials in the Getting Started section. + +We strive to write factual content in an accessible and well-written English. To +contribute, you should also read: + +1. The :ref:`doc_docs_writing_guidelines`. There, you will find rules and + recommendations to write in a way that everyone understands. +2. The content guidelines. They explain the principles we follow to write the + documentation and the kind of content we accept. + +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 less convenient to edit than a wiki, this Git repository is where we +write the documentation. Having direct access to the source files in a revision +control system is a plus to ensure our documentation quality. + +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. + Editing pages online -------------------- @@ -59,108 +96,25 @@ 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:``). +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 -------------------------------- - -The Godot documentation is intended as a comprehensive reference manual for the -Godot game engine. It is not meant to contain step-by-step tutorials, with the -exception of two game creation tutorials in the Getting Started section. - -We strive to write objective content in accessible and well-written English. To -contribute, you should also read: - -- The :ref:`doc_docs_writing_guidelines`. There, you will find rules to write - -- Tutorial: a page aiming at explaining how to use one or more concepts in the - editor or scripts in order to achieve a specific goal with a learning purpose - (e.g. "Making a simple 2d Pong game", "Applying forces to an object"). -- Documentation: a page describing precisely one and only one concept at a time, - if possible exhaustively (e.g. the list of methods of the Sprite class, or an - overview of the input management in Godot). - -You are free to write the kind of documentation you wish, as long as you respect -the following rules (and the ones on the repo). +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``. Titles ------- +~~~~~~ Always begin pages with their title and a Sphinx reference name: @@ -172,27 +126,56 @@ Always begin pages with their title and a Sphinx reference name: ====================== The reference allows linking to this page using the ``:ref:`` format, e.g. -``:ref:`doc_insert_your_title_here``` would link to the above example page -(note the lack of leading underscore in the reference). +``:ref:`doc_insert_your_title_here``` would link to the above example page (note +the lack of leading underscore in the reference). -Also, avoid American CamelCase titles: title's first word should begin -with a capitalized letter, and every following word should not. Thus, -this is a good example: +Write your titles like plain sentences, without capitalizing each word: -- Insert your title here +- **Good**: Understanding signals in Godot +- **Bad**: Understanding Signals In Godot -And this is a bad example: +Only propers nouns, projects, people, and node class names should have their +first letter capitalized. -- Insert Your Title Here +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 ` -Only project, people and node class names should have capitalized first -letter. License ------- This documentation and every page it contains is published under the terms of -the `Creative Commons Attribution 3.0 license (CC-BY-3.0) `_, with attribution to "Juan Linietsky, Ariel Manzur and the Godot community". +the `Creative Commons Attribution 3.0 license (CC-BY-3.0) +`_, with +attribution to "Juan Linietsky, Ariel Manzur and the Godot community". By contributing to the documentation on the GitHub repository, you agree that your changes are distributed under this license. From deade79fbcbd43d0a85698aefe68e5e7e200cae2 Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Fri, 25 Sep 2020 12:49:09 -0600 Subject: [PATCH 06/10] Add introduction and split TOC in contributing/index.rst --- community/contributing/index.rst | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/community/contributing/index.rst b/community/contributing/index.rst index 02a84776d..c9984825e 100644 --- a/community/contributing/index.rst +++ b/community/contributing/index.rst @@ -1,17 +1,42 @@ Contributing ============ +Everyone is most welcome to contribute to Godot. Here are some ways in which you can contribute to the project: + +- Improving the engine by fixing bugs, coding new features, or refining existing ones. +- Writing or proofreading documentation. You can contribute both to this reference manual or the code reference. +- Translating the editor or documentation from English to other languages. +- Reporting issues or `writing detailed proposals `__. + +Getting started +--------------- + .. toctree:: :maxdepth: 1 :name: toc-community-contributing ways_to_contribute + +Contributing to the engine +-------------------------- + +.. toctree:: + :maxdepth: 1 + :name: toc-community-contributing-to-the-engine + best_practices_for_engine_contributors pr_workflow bisecting_regressions code_style_guidelines bug_triage_guidelines - content_guidelines + +Writing documentation +--------------------- + +.. toctree:: + :maxdepth: 1 + :name: toc-community-contributing-to-documentation + documentation_guidelines docs_writing_guidelines updating_the_class_reference From 1389aa487333ab4052f1a98102df095746b3029d Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Fri, 13 Nov 2020 07:55:24 -0600 Subject: [PATCH 07/10] Edit contribution guidelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Removed some typographic marks, fix missing newlines, phrasing... Co-authored-by: Rémi Verschelde --- .../contributing/building_the_manual.rst | 2 +- .../class_reference_writing_guidelines.rst | 15 +++---- .../contributing/documentation_guidelines.rst | 41 ++++++++++--------- .../updating_the_class_reference.rst | 9 ++-- 4 files changed, 35 insertions(+), 32 deletions(-) diff --git a/community/contributing/building_the_manual.rst b/community/contributing/building_the_manual.rst index b1f11b572..473114852 100644 --- a/community/contributing/building_the_manual.rst +++ b/community/contributing/building_the_manual.rst @@ -44,7 +44,7 @@ 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 +.. code:: sh # On Linux/macOS make html SPHINXOPTS=-j2 diff --git a/community/contributing/class_reference_writing_guidelines.rst b/community/contributing/class_reference_writing_guidelines.rst index 68114481f..f76fdd173 100644 --- a/community/contributing/class_reference_writing_guidelines.rst +++ b/community/contributing/class_reference_writing_guidelines.rst @@ -12,7 +12,7 @@ built-in node types. To learn to submit your changes to the Godot project using the Git version control system, see :ref:`doc_updating_the_class_reference`. -Each class's reference is contained in an XML file like the one below: +The reference for each class is contained in an XML file like the one below: .. code-block:: xml @@ -59,12 +59,13 @@ how they work in Godot's source code, and fill their tag. Our job is to complete or improve the text in these tags: -- -- -- -- -- -- +- `` +- `` +- `` +- `` (in its `` tag; return types and arguments don't take separate documentation strings) +- `` +- `` (in its `` tag; arguments don't take separate documentation strings) +- `` Write in a clear and simple language. Always follow the :ref:`writing guidelines ` to keep your descriptions short and easy to read. diff --git a/community/contributing/documentation_guidelines.rst b/community/contributing/documentation_guidelines.rst index 330898c1e..f1367d333 100644 --- a/community/contributing/documentation_guidelines.rst +++ b/community/contributing/documentation_guidelines.rst @@ -17,7 +17,7 @@ Getting started To modify or create pages in the reference manual, you need to edit ``.rst`` files in the `godot-docs GitHub repository `_. Modifying those pages in a pull -request and triggers a rebuild of the online documentation upon merging. +request triggers a rebuild of the online documentation upon merging. .. seealso:: For details on Git usage and the pull request workflow, please refer to the :ref:`doc_pr_workflow` page. Most of what it describes @@ -38,7 +38,7 @@ The Godot documentation is intended as a comprehensive reference manual for the Godot game engine. It is not meant to contain step-by-step tutorials, except for two game creation tutorials in the Getting Started section. -We strive to write factual content in an accessible and well-written English. To +We strive to write factual content in an accessible and well-written language. To contribute, you should also read: 1. The :ref:`doc_docs_writing_guidelines`. There, you will find rules and @@ -60,12 +60,12 @@ control system is a plus to ensure our documentation quality. Editing existing pages ~~~~~~~~~~~~~~~~~~~~~~ -To edit an existing page, locate its .rst source file and open it in your +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 +edited here.** They are automatically generated from Godot’s `XML class +reference `__. +See `Contribute to the Class Reference `__ for details. @@ -81,17 +81,18 @@ and to log in to use it. Once logged in, you can propose change like so: 1. Click the **Edit on GitHub** button. 2. On the GitHub page you're taken to, click the pencil icon in the top-right - corner near the **Raw**, **Blame**, and **History** buttons. It has the - tooltip "Edit the file in a fork of this project". + corner near the **Raw**, **Blame**, and **Delete** buttons. It has the + tooltip "Fork this project and edit the file". 3. Edit the text in the text editor. 4. At the bottom of the web page, summarize the changes you made and click the - button **Propose file change**. + button **Propose file change**. Make sure to replace the placeholder "Update file.rst" + by a short but clear one-line description, as this is the commit title. 5. On the following screens, click the **Create pull request** button until you see a message like *Username wants to merge 1 commit into godotengine:master - from Username:patch-6*. + from Username:patch-1*. 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. @@ -99,15 +100,15 @@ they're good. They may also make changes or ask you to do so before merging. 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 +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. ``.. +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 +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 @@ -131,8 +132,8 @@ the lack of leading underscore in the reference). Write your titles like plain sentences, without capitalizing each word: -- **Good**: Understanding signals in Godot -- **Bad**: Understanding Signals In Godot +- **Good:** Understanding signals in Godot +- **Bad:** Understanding Signals In Godot Only propers nouns, projects, people, and node class names should have their first letter capitalized. @@ -145,7 +146,7 @@ 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 +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. @@ -153,7 +154,7 @@ 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 +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 @@ -161,7 +162,7 @@ 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 +tutorial, by placing them into a ``files/`` folder next to the ``.rst`` file, and using this inline markup: .. code:: rst diff --git a/community/contributing/updating_the_class_reference.rst b/community/contributing/updating_the_class_reference.rst index cce6c1d84..812dd9b85 100644 --- a/community/contributing/updating_the_class_reference.rst +++ b/community/contributing/updating_the_class_reference.rst @@ -55,7 +55,7 @@ You will find a complete breakdown of these steps below. `_. .. warning:: Always edit the API reference through these source XML files. Do - not edit the generated .rst files :ref:`in the online documentation + not edit the generated ``.rst`` files :ref:`in the online documentation `, hosted in the `godot-docs `_ repository. @@ -96,7 +96,7 @@ up your repository if you run into any issues with Git. git checkout -b your-new-branch-name The new branch is the same as your master branch until you start to write API -docs. In the ``doc/`` folder, you will find the class reference. +docs. You will find the class reference in the ``doc/classes/`` folder. Keeping your local clone up-to-date ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -149,10 +149,11 @@ following commands instead: :: - git fetch upstream git reset --hard upstream master + git fetch upstream + git reset --hard upstream/master **Warning:** The above command will reset your branch to the state of the - ``upstream master`` branch. It will discard all local changes. Make sure to + ``upstream/master`` branch. It will discard all local changes. Make sure to only run this *before* you make important changes. Another option is to delete the branch you're working on, synchronize the master From 1827f109373a8736e4f759ab1abf011d7824eac9 Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Fri, 13 Nov 2020 08:49:59 -0600 Subject: [PATCH 08/10] Edit contributing guidelines Add links to the README Simplify building the manual Update class reference writing guidelines based on review notes. Re-add lost changes in rebase. Address review comments in documentation guidelines --- README.md | 5 +- .../contributing/building_the_manual.rst | 55 ++---- .../class_reference_writing_guidelines.rst | 180 ++++++++++++------ .../contributing/documentation_guidelines.rst | 34 ++-- .../editor_and_docs_localization.rst | 2 +- community/contributing/index.rst | 1 + .../updating_the_class_reference.rst | 72 +++---- 7 files changed, 201 insertions(+), 148 deletions(-) diff --git a/README.md b/README.md index d1ba68ff1..6888148ca 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,9 @@ 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) +3. [Content guidelines](https://docs.godotengine.org/en/latest/community/contributing/content_guidelines.html) +4. [Writing guidelines](https://docs.godotengine.org/en/latest/community/contributing/docs_writing_guidelines.html) +5. [Translating the documentation](https://docs.godotengine.org/en/latest/community/contributing/editor_and_docs_localization.html) ## License diff --git a/community/contributing/building_the_manual.rst b/community/contributing/building_the_manual.rst index 473114852..ae4ae3652 100644 --- a/community/contributing/building_the_manual.rst +++ b/community/contributing/building_the_manual.rst @@ -7,20 +7,24 @@ 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: +To get started, you need to: -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 +1. Clone the `godot-docs repository `__. +2. Install `Sphinx `__ +3. To build the docs as HTML files, install the `readthedocs.org theme + `__. +4. Install the Sphinx extensions defined in the `godot-docs repository + `__ ``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. +`__. Ensure that you install and use Python 3. Here are +the commands to clone the repository and then install all requirements. .. code:: sh - pip install -r requirements.txt + git clone https://github.com/godotengine/godot-docs.git + 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 @@ -32,13 +36,17 @@ folder of this repository with the following command: .. code:: sh - make html + # On Linux and MacOS + make html + + # On Windows, you need to execute the ``make.bat`` file instead. + make.bat html If you run into errors, you may try the following command: .. code:: sh - make SPHINXBUILD=~/.local/bin/sphinx-build html + 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 @@ -46,11 +54,11 @@ up compilation by running: .. code:: sh - # On Linux/macOS - make html SPHINXOPTS=-j2 + # On Linux/macOS + make html SPHINXOPTS=-j2 - # On Windows - set SPHINXOPTS=-j2 && make html + # On Windows + set SPHINXOPTS=-j2 && make html The compilation will take some time as the ``classes/`` folder contains hundreds of files. @@ -68,23 +76,6 @@ from the final HTML documentation but will keep the rest intact. `__ 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: @@ -92,10 +83,6 @@ program manually: 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 ----------------------------------- diff --git a/community/contributing/class_reference_writing_guidelines.rst b/community/contributing/class_reference_writing_guidelines.rst index f76fdd173..68be0380e 100644 --- a/community/contributing/class_reference_writing_guidelines.rst +++ b/community/contributing/class_reference_writing_guidelines.rst @@ -16,34 +16,45 @@ The reference for each class is contained in an XML file like the one below: .. code-block:: xml - + - Base node for 2D system. + A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index. - Base node for 2D system. Node2D contains a position, rotation and scale, which is used to position and animate. It can alternatively be used with a custom 2D transform ([Matrix32]). A tree of Node2Ds allows complex hierarchies for animation and positioning. + A 2D game object, with a transform (position, rotation, and scale). All 2D nodes, including physics objects and sprites, inherit from Node2D. Use Node2D as a parent node to move, scale and rotate children in a 2D project. Also gives control of the node's render order. + + https://docs.godotengine.org/en/latest/tutorials/2d/custom_drawing_in_2d.html + https://github.com/godotengine/godot-demo-projects/tree/master/2d + - - + + + + - Sets the position of the 2D node. + Multiplies the current scale by the [code]ratio[/code] vector. [...] - - + + + + + Translates the node by the given [code]offset[/code] in local coordinates. - + + Global position. [...] - + + Z index. Controls the order in which the nodes render. A node with a higher Z index will display in front of others. @@ -54,15 +65,16 @@ The reference for each class is contained in an XML file like the one below: It starts with brief and long descriptions. In the generated docs, the brief description is always at the top of the page, while the long description lies below the list of methods, variables, and constants. You can find methods, -member variables, constants, and signals in separate XML nodes. For each, learn -how they work in Godot's source code, and fill their tag. +member variables, constants, and signals in separate XML nodes. -Our job is to complete or improve the text in these tags: +For each, you want to learn how they work in Godot's source code. Then, fill +their documentation by completing or improving the text in these tags: - `` - `` - `` -- `` (in its `` tag; return types and arguments don't take separate documentation strings) +- `` (in its `` tag; return types and arguments don't take separate + documentation strings) - `` - `` (in its `` tag; arguments don't take separate documentation strings) - `` @@ -72,6 +84,8 @@ Write in a clear and simple language. Always follow the :ref:`writing guidelines **Do not leave empty lines** in the descriptions: each line in the XML file will result in a new paragraph, even if it is empty. +.. _doc_class_reference_writing_guidelines_editing_xml: + How to edit class XML --------------------- @@ -80,20 +94,27 @@ reference. The folder contains an XML file for each class. The XML lists the constants and methods you will find in the class reference. Godot generates and updates the XML automatically. +.. note:: For some modules in the engine's source code, you'll find the XML + files in the ``modules//doc_classes/`` directory instead. + Edit it using your favorite text editor. If you use a code editor, make sure -that it doesn't change the indent style: you should use tabs for the XML, and +that it doesn't change the indent style: you should use tabs for the XML and four spaces inside BBCode-style blocks. More on that below. -To check that the modifications you've made are correct in the -generated documentation, you need to build Godot. To learn how, read the -:ref:`compilation guide `. Then, run the editor and open -the help for the page you modified. +To check that the modifications you've made are correct in the generated +documentation, navigate to the ``doc/`` folder and run the command ``make rst``. +This will convert the XML files to the online documentation's format and output +errors if anything's wrong. + +Alternatively, you can build Godot and open the modified page in the built-in +code reference. To learn how to compile the engine, read the :ref:`compilation +guide `. We recommend using a code editor that supports XML files like Vim, Atom, Code, Notepad++, or another to comfortably edit the file. You can also use their search feature to find classes and properties quickly. -.. _doc_updating_the_class_reference_bbcode: +.. _doc_class_reference_writing_guidelines_bbcode: Improve formatting with BBCode style tags ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -101,33 +122,39 @@ Improve formatting with BBCode style tags Godot's class reference supports BBCode-like tags. They add nice formatting to the text. Here's the list of available tags: -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| Tag | Effect | Usage | Result | -+===========================+================================+===================================+===================================================+ -| [Class] | Link a class | Move the [Sprite]. | Move the :ref:`class_sprite`. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [method methodname] | Link to a method in this class | Call [method hide]. | See :ref:`hide `. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [method Class.methodname] | Link to another class's method | Call [method Spatial.hide]. | See :ref:`hide `. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [member membername] | Link to a member in this class | Get [member scale]. | Get :ref:`scale `. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [member Class.membername] | Link to another class's member | Get [member Node2D.scale]. | Get :ref:`scale `. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [signal signalname] | Link to a signal in this class | Emit [signal renamed]. | Emit :ref:`renamed `. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [signal Class.signalname] | Link to another class's signal | Emit [signal Node.renamed]. | Emit :ref:`renamed `. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [b] [/b] | Bold | Some [b]bold[/b] text. | Some **bold** text. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [i] [/i] | Italic | Some [i]italic[/i] text. | Some *italic* text. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [code] [/code] | Monospace | Some [code]monospace[/code] text. | Some ``monospace`` text. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [kbd] [/kbd] | Keyboard/mouse shortcut | Some [kbd]Ctrl + C[/kbd] key. | Some :kbd:`Ctrl + C` key. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [codeblock] [/codeblock] | Multiline preformatted block | *See below.* | *See below.* | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| Tag | Effect | Usage | Result | ++============================+======================================+===================================+===================================================+ +| [Class] | Link a class | Move the [Sprite]. | Move the :ref:`class_sprite`. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [method methodname] | Link to a method in this class | Call [method hide]. | See :ref:`hide `. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [method Class.methodname] | Link to another class's method | Call [method Spatial.hide]. | See :ref:`hide `. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [member membername] | Link to a member in this class | Get [member scale]. | Get :ref:`scale `. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [member Class.membername] | Link to another class's member | Get [member Node2D.scale]. | Get :ref:`scale `. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [signal signalname] | Link to a signal in this class | Emit [signal renamed]. | Emit :ref:`renamed `. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [signal Class.signalname] | Link to another class's signal | Emit [signal Node.renamed]. | Emit :ref:`renamed `. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [b] [/b] | Bold | Some [b]bold[/b] text. | Some **bold** text. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [i] [/i] | Italic | Some [i]italic[/i] text. | Some *italic* text. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [code] [/code] | Monospace | Some [code]monospace[/code] text. | Some ``monospace`` text. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [kbd] [/kbd] | Keyboard/mouse shortcut | Some [kbd]Ctrl + C[/kbd] key. | Some :kbd:`Ctrl + C` key. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [codeblock] [/codeblock] | Multiline preformatted block | *See below.* | *See below.* | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [codeblocks] [/codeblocks] | [codeblock] for multiple languages | *See below.* | *See below.* | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [gdscript] [/gdscript] | GDScript codeblock tab in codeblocks | *See below.* | *See below.* | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [csharp] [/csharp] | C# codeblock tab in codeblocks | *See below.* | *See below.* | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``, always use **four spaces** for indentation. The parser will delete tabs. For @@ -135,14 +162,61 @@ example: .. code-block:: none - [codeblock] func _ready(): var sprite = get_node("Sprite") - print(sprite.get_pos()) [/codeblock] + [codeblock] + func _ready(): + var sprite = get_node("Sprite") + print(sprite.get_pos()) + [/codeblock] Will display as: .. code-block:: gdscript - func _ready(): var sprite = get_node("Sprite") print(sprite.get_pos()) + func _ready(): + var sprite = get_node("Sprite") + print(sprite.get_pos()) + +If you need to have different code version in GDScript and C#, use +``[codeblocks]`` instead. If you use ``[codeblocks]``, you also need to have at +least one of the language-specific tags, ``[gdscript]`` and ``[csharp]``. + +Always write GDScript code examples first! You can use this `experimental code +translation tool `_ to speed up your +workflow. + +.. code-block:: none + + [codeblocks] + [gdscript] + func _ready(): + var sprite = get_node("Sprite") + print(sprite.get_pos()) + [/gdscript] + [csharp] + public override void _Ready() + { + var sprite = GetNode("Sprite"); + GD.Print(sprite.GetPos()); + } + [/csharp] + [/codeblocks] + +The above will display as: + +.. tabs:: + .. code-tab:: gdscript GDScript + + func _ready(): + var sprite = get_node("Sprite") + print(sprite.get_pos()) + + .. code-tab:: csharp + + public override void _Ready() + { + var sprite = GetNode("Sprite"); + GD.Print(sprite.GetPos()); + } To denote important information, add a paragraph starting with "[b]Note:[/b]" at the end of the description: @@ -157,16 +231,14 @@ the end of the description: .. code-block:: none - [b]Warning:[/b] If this property is set to [code]true[/code], it allows - clients to execute arbitrary code on the server. + [b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server. For deprecated properties, add a paragraph starting with "[i]Deprecated.[/i]". Notice the use of italics instead of bold: .. code-block:: none - [i]Deprecated.[/i] This property has been replaced by [member - other_property]. + [i]Deprecated.[/i] This property has been replaced by [member other_property]. In all the paragraphs described above, make sure the punctuation is part of the BBCode tags for consistency. diff --git a/community/contributing/documentation_guidelines.rst b/community/contributing/documentation_guidelines.rst index f1367d333..6befc6de2 100644 --- a/community/contributing/documentation_guidelines.rst +++ b/community/contributing/documentation_guidelines.rst @@ -49,7 +49,7 @@ contribute, you should also read: Contributing changes -------------------- -**Pull Requests should use the ``master`` branch by default**. Only make Pull +**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. @@ -69,6 +69,9 @@ See `Contribute to the Class Reference `__ for details. +.. seealso:: To build the manual and test changes on your computer, see + :ref:`doc_building_the_manual` + Editing pages online -------------------- @@ -100,19 +103,20 @@ they're good. They may also make changes or ask you to do so before merging. Adding new pages ---------------- +Before adding a new page, please ensure that it fits in the documentation: + +1. Look for `existing issues + `_ or open a new one to see + if the page is necessary. +2. Ensure there isn't a page that already covers the topic. +3. Read our :ref:`doc_content_guidelines`. + 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:``). +want to add a file to, e.g. ``tutorials/3d/light_baking.rst``. 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``. +e.g. ``tutorials/3d/index.rst``). Add your new filename to the list on a new +line, using a relative path and no extension, e.g. here ``light_baking``. Titles ~~~~~~ @@ -126,6 +130,8 @@ Always begin pages with their title and a Sphinx reference name: Insert your title here ====================== +The reference ``_doc_insert_your_title_here`` and the title should match. + The reference allows linking to this page using the ``:ref:`` format, e.g. ``:ref:`doc_insert_your_title_here``` would link to the above example page (note the lack of leading underscore in the reference). @@ -148,8 +154,10 @@ 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. +`__ for more details. To learn +how to use Sphinx directives like ``.. note::`` or ``.. seealso::``, check out +the `Sphinx directives documentation +`__. Adding images and attachments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/community/contributing/editor_and_docs_localization.rst b/community/contributing/editor_and_docs_localization.rst index 844258bfd..1b3e2db34 100644 --- a/community/contributing/editor_and_docs_localization.rst +++ b/community/contributing/editor_and_docs_localization.rst @@ -324,7 +324,7 @@ breaks if they are not part of the original translation. .. seealso:: See our documentation for class reference writers for the :ref:`list of - BBCode-like tags ` which are used + BBCode-like tags ` which are used throughout the class reference. Offline translation and testing diff --git a/community/contributing/index.rst b/community/contributing/index.rst index c9984825e..6088aa5ff 100644 --- a/community/contributing/index.rst +++ b/community/contributing/index.rst @@ -38,6 +38,7 @@ Writing documentation :name: toc-community-contributing-to-documentation documentation_guidelines + content_guidelines docs_writing_guidelines updating_the_class_reference class_reference_writing_guidelines diff --git a/community/contributing/updating_the_class_reference.rst b/community/contributing/updating_the_class_reference.rst index 812dd9b85..4fdf0ddd1 100644 --- a/community/contributing/updating_the_class_reference.rst +++ b/community/contributing/updating_the_class_reference.rst @@ -41,6 +41,9 @@ You can find the source files for the class reference in Godot's GitHub repository: `doc/classes/ `_. +.. note:: For some modules in the engine's source code, you'll find the XML + files in the ``modules//doc_classes/`` directory instead. + There are five steps to update the class reference: 1. Fork `Godot's repository `_ @@ -103,7 +106,7 @@ Keeping your local clone up-to-date Other writers contribute to Godot's documentation. Your local repository will fall behind it. You will have to synchronize it, especially if other -contributors update the class reference while working on it. +contributors update the class reference while you are working on it. First, add an ``upstream`` Git *remote*. Remotes are links to online repositories from which you can download new files. The following command registers a new @@ -113,27 +116,6 @@ remote named "upstream" that links to the original Godot repository. git remote add upstream https://github.com/godotengine/godot -You can check the list of all remote servers with this command: - -:: - - git remote -v - -You should have two remotes: - -1. ``origin``, corresponding to your fork on GitHub. Git adds it by default when - you clone a repository. -2. ``upstream``, that you just added. - -The output should look like the following: - -:: - - origin https://github.com/your_name/godot.git (fetch) origin - https://github.com/your_name/godot.git (push) upstream - https://github.com/godotengine/godot.git (fetch) upstream - https://github.com/godotengine/godot.git (push) - Each time you want to synchronize your branch with the upstream repository, enter: @@ -161,13 +143,19 @@ branch with the Godot repository, and create a new branch: :: - git checkout master git branch -d your-new-branch-name git pull --rebase - upstream master git checkout -b your-new-branch-name + git checkout master + git pull --rebase upstream master + # Creates a new branch and checks out to it + git checkout -b your-new-branch-name If you're feeling lost by now, come to our `IRC channels `_ and ask for help. Experienced Git users will give you a hand. +Alternatively, you can join the `Godot Discord server +`_ and participate in the ``#documentation`` +channel. + Submitting your changes ~~~~~~~~~~~~~~~~~~~~~~~ @@ -188,33 +176,29 @@ in the GitHub documentation. .. warning:: - You should avoid editing files directly on GitHub in the godot engine - repository. As hundreds of contributors work on the engine, the Git history - must stay clean. Each commit should bundle all related improvements you make - to the class reference. + Unless you make minor changes, like fixing a typo, we do not recommend using the GitHub web editor to edit the class reference's XML. - Editing from GitHub creates a new branch and Pull Request every time you - save your changes. Suppose days pass before your changes get a review. In - that case, you won't be able to update to the latest version of the - repository cleanly. Also, it's harder to keep clean indents with GitHub's - text editor. And they're essential in the class reference. + It lacks features to edit XML well, like keeping indentations consistent, and it does not allow amending commits based on reviews. + + Also, it doesn't allow you to test your changes in the engine or with validation + scripts as described in + :ref:`doc_class_reference_writing_guidelines_editing_xml`. Updating the documentation template ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When classes are modified in the source code, the documentation template might become outdated. To make sure that you are editing an up-to-date version, you first need to compile Godot (you can follow the :ref:`doc_introduction_to_the_buildsystem` page), and then run the following command (assuming 64-bit Linux): +When you create a new class or modify the engine's API, you need to re-generate the XML files in ``doc/classes/``. + +To do so, you first need to compile Godot. See the +:ref:`doc_introduction_to_the_buildsystem` page to learn how. Then, execute the +compiled godot executable with the ``--doctool`` option. If you're on 64-bit +Linux, the command is: :: ./bin/godot.linuxbsd.tools.64 --doctool . -The XML files in doc/classes should then be up-to-date with current Godot Engine features. You can then check what changed using the ``git diff`` command. If there are changes to other classes than the one you are planning to document, please commit those changes first before starting to edit the template: - -:: - - git add doc/classes/*.xml - git commit -m "Sync classes reference template with current code base" - -You are now ready to edit this file to add stuff. - -**Note:** If this has been done recently by another contributor, you don't forcefully need to go through these steps (unless you know that the class you plan to edit *has* been modified recently). +The XML files in doc/classes should then be up-to-date with current Godot Engine +features. You can then check what changed using the ``git diff`` command. Please +only include changes that are relevant to your work on the API in your commits. +You can discard changes in other XML files using ``git checkout``. From d47594017876c594eb2afe166c5ca63f2a1fb822 Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Fri, 13 Nov 2020 11:05:40 -0600 Subject: [PATCH 09/10] Update references to the docs guidelines We split some pages into two and some remaining references were leading to an irrelevant page. --- about/introduction.rst | 2 +- community/contributing/ways_to_contribute.rst | 12 ++++++------ development/cpp/custom_modules_in_cpp.rst | 2 +- tutorials/ui/bbcode_in_richtextlabel.rst | 5 +++-- 4 files changed, 11 insertions(+), 10 deletions(-) diff --git a/about/introduction.rst b/about/introduction.rst index 20509d4bb..bcfbbbdeb 100644 --- a/about/introduction.rst +++ b/about/introduction.rst @@ -102,7 +102,7 @@ relatively intuitive: which is also available directly within the engine's script editor. It is generated automatically from a file in the main source repository, therefore the generated files of the documentation are not meant to be modified. See - :ref:`doc_updating_the_class_reference` for details. + :ref:`doc_class_reference_writing_guidelines` for details. In addition to this documentation you may also want to take a look at the various `Godot demo projects `_. diff --git a/community/contributing/ways_to_contribute.rst b/community/contributing/ways_to_contribute.rst index fbe62ce5a..a9824a253 100644 --- a/community/contributing/ways_to_contribute.rst +++ b/community/contributing/ways_to_contribute.rst @@ -176,13 +176,13 @@ Contributing to the documentation There are two separate resources referred to as "documentation" in Godot: -- **The class reference.** This is the documentation for the complete Godot - API as exposed to GDScript and the other scripting languages. It can be - consulted offline, directly in Godot's code editor, or online at - :ref:`Godot API `. - To contribute to the class reference, you have to edit the +- **The class reference.** This is the documentation for the complete Godot API + as exposed to GDScript and the other scripting languages. It can be consulted + offline, directly in Godot's code editor, or online at :ref:`Godot API + `. To contribute to the class reference, you have to edit the `doc/base/classes.xml` in Godot's Git repository, and make a pull request. - See :ref:`doc_updating_the_class_reference` for more details. + See :ref:`doc_updating_the_class_reference` and + :ref:`doc_class_reference_writing_guidelines` for more details. - **The tutorials and engine documentation and its translations.** This is the part you are reading now, which is distributed in the HTML, PDF and EPUB formats. Its contents diff --git a/development/cpp/custom_modules_in_cpp.rst b/development/cpp/custom_modules_in_cpp.rst index dfcfd455d..fff7187a4 100644 --- a/development/cpp/custom_modules_in_cpp.rst +++ b/development/cpp/custom_modules_in_cpp.rst @@ -573,7 +573,7 @@ Now if you go to the ``godot/modules/summator/doc_classes`` folder, you will see that it contains a ``Summator.xml`` file, or any other classes, that you referenced in your ``get_doc_classes`` function. -Edit the file(s) following :ref:`doc_updating_the_class_reference` and recompile the engine. +Edit the file(s) following :ref:`doc_class_reference_writing_guidelines` and recompile the engine. Once the compilation process is finished, the docs will become accessible within the engine's built-in documentation system. diff --git a/tutorials/ui/bbcode_in_richtextlabel.rst b/tutorials/ui/bbcode_in_richtextlabel.rst index 06ab30cfd..05ac7e278 100644 --- a/tutorials/ui/bbcode_in_richtextlabel.rst +++ b/tutorials/ui/bbcode_in_richtextlabel.rst @@ -15,8 +15,9 @@ a :ref:`class_RichTextLabel`. :ref:`class_RichTextLabel` allows the display of complex text markup in a Control. It has a built-in API for generating the markup, but can also parse a BBCode. -Note that the BBCode tags can also be used, to some extent, in the -:ref:`XML source of the class reference `. +Note that the BBCode tags can also be used, to some extent, in the XML source of +the class reference. For more information, see +:ref:`doc_class_reference_writing_guidelines`. Using BBCode ------------ From 87a87205fb887f7787cbc823002ddd176931f9f6 Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Fri, 13 Nov 2020 14:09:07 -0600 Subject: [PATCH 10/10] Rewrite contributing/index, rename pages, update references --- README.md | 2 +- .../class_reference_writing_guidelines.rst | 2 +- ... => contributing_to_the_documentation.rst} | 4 +- community/contributing/index.rst | 74 +++++++++++++++++-- .../updating_the_class_reference.rst | 2 +- community/contributing/ways_to_contribute.rst | 4 +- 6 files changed, 74 insertions(+), 14 deletions(-) rename community/contributing/{documentation_guidelines.rst => contributing_to_the_documentation.rst} (98%) diff --git a/README.md b/README.md index 6888148ca..75270bea1 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ To get started, head to the [Contributing section](https://docs.godotengine.org/ 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) +1. [Contributing to the online manual](https://docs.godotengine.org/en/latest/community/contributing/contibuting_to_the_documentation.html) 2. [Contributing to the class reference](https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html) 3. [Content guidelines](https://docs.godotengine.org/en/latest/community/contributing/content_guidelines.html) 4. [Writing guidelines](https://docs.godotengine.org/en/latest/community/contributing/docs_writing_guidelines.html) diff --git a/community/contributing/class_reference_writing_guidelines.rst b/community/contributing/class_reference_writing_guidelines.rst index 68be0380e..46bf713e8 100644 --- a/community/contributing/class_reference_writing_guidelines.rst +++ b/community/contributing/class_reference_writing_guidelines.rst @@ -10,7 +10,7 @@ built-in node types. .. seealso:: To learn to submit your changes to the Godot project using the Git version - control system, see :ref:`doc_updating_the_class_reference`. + control system, see :ref:`doc_updating_the_class_reference_with_git`. The reference for each class is contained in an XML file like the one below: diff --git a/community/contributing/documentation_guidelines.rst b/community/contributing/contributing_to_the_documentation.rst similarity index 98% rename from community/contributing/documentation_guidelines.rst rename to community/contributing/contributing_to_the_documentation.rst index 6befc6de2..8d39911e2 100644 --- a/community/contributing/documentation_guidelines.rst +++ b/community/contributing/contributing_to_the_documentation.rst @@ -1,4 +1,4 @@ -.. _doc_documentation_guidelines: +.. _doc_contributing_to_the_documentation: Contributing to the documentation ================================= @@ -29,7 +29,7 @@ request triggers a rebuild of the online documentation upon merging. the :ref:`Godot API ` section of this documentation from them. If you want to update the description of a class, its methods, or properties, read - :ref:`doc_updating_the_class_reference`. + :ref:`doc_updating_the_class_reference_with_git`. What is the Godot documentation ------------------------------- diff --git a/community/contributing/index.rst b/community/contributing/index.rst index 6088aa5ff..3905328c8 100644 --- a/community/contributing/index.rst +++ b/community/contributing/index.rst @@ -1,25 +1,36 @@ Contributing ============ -Everyone is most welcome to contribute to Godot. Here are some ways in which you can contribute to the project: +Everyone is most welcome to contribute to Godot. Here are some ways in which you +can contribute to the project: - Improving the engine by fixing bugs, coding new features, or refining existing ones. -- Writing or proofreading documentation. You can contribute both to this reference manual or the code reference. +- Writing or proofreading documentation. You can contribute both to this + reference manual or the code reference. - Translating the editor or documentation from English to other languages. -- Reporting issues or `writing detailed proposals `__. +- Reporting issues or `writing detailed proposals + `__. Getting started --------------- +You would like to contribute but you don't know how or what to do? You can get +answers below. + .. toctree:: :maxdepth: 1 - :name: toc-community-contributing + :name: toc-community-getting-started ways_to_contribute +.. _doc_community_contributing_to_the_engine: + Contributing to the engine -------------------------- +The guides below explain how to contribute to the engine's core. You will learn +about the code style, the contribution workflow, and more. + .. toctree:: :maxdepth: 1 :name: toc-community-contributing-to-the-engine @@ -30,17 +41,66 @@ Contributing to the engine code_style_guidelines bug_triage_guidelines +.. _doc_community_writing_documentation: + Writing documentation --------------------- +We always need help to improve the documentation, be it the class reference or +the manual. Below, you can find our content and writing guidelines and +concrete guides to make changes to the documentation. + +Guidelines +~~~~~~~~~~ + +Here are the principles and guidelines we strive to follow to write accessible +documentation. + .. toctree:: :maxdepth: 1 - :name: toc-community-contributing-to-documentation + :name: toc-community-writing-guidelines - documentation_guidelines content_guidelines docs_writing_guidelines + +Writing the manual +~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + :name: toc-community-documentation + + contributing_to_the_documentation + building_the_manual + +Class reference guides +~~~~~~~~~~~~~~~~~~~~~~ + +The pages below focus on the class reference. + +As the reference is included in the Godot editor, its source files are part of +the `godot repository `_. We use XML files +to write it, so the process to contribute to the class reference differs from +writing the online manual. + +.. toctree:: + :maxdepth: 1 + :name: toc-community-class-reference + updating_the_class_reference class_reference_writing_guidelines + +.. _doc_community_translating_the_documentation: + +Translating the documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The community is always working hard on making Godot and its documentation +available to more people. Localizing the documentation is a colossal and ongoing +effort you can be part of. + +.. toctree:: + :maxdepth: 1 + :name: toc-community-localization + editor_and_docs_localization - building_the_manual diff --git a/community/contributing/updating_the_class_reference.rst b/community/contributing/updating_the_class_reference.rst index 4fdf0ddd1..1e395188b 100644 --- a/community/contributing/updating_the_class_reference.rst +++ b/community/contributing/updating_the_class_reference.rst @@ -1,4 +1,4 @@ -.. _doc_updating_the_class_reference: +.. _doc_updating_the_class_reference_with_git: Contributing to the class reference with Git ============================================ diff --git a/community/contributing/ways_to_contribute.rst b/community/contributing/ways_to_contribute.rst index a9824a253..6eb38ff4d 100644 --- a/community/contributing/ways_to_contribute.rst +++ b/community/contributing/ways_to_contribute.rst @@ -181,7 +181,7 @@ There are two separate resources referred to as "documentation" in Godot: offline, directly in Godot's code editor, or online at :ref:`Godot API `. To contribute to the class reference, you have to edit the `doc/base/classes.xml` in Godot's Git repository, and make a pull request. - See :ref:`doc_updating_the_class_reference` and + See :ref:`doc_updating_the_class_reference_with_git` and :ref:`doc_class_reference_writing_guidelines` for more details. - **The tutorials and engine documentation and its translations.** This is the part you are reading @@ -189,7 +189,7 @@ There are two separate resources referred to as "documentation" in Godot: are generated from plain text files in the reStructured Text (rst) format, to which you can contribute via pull requests on the `godot-docs `_ GitHub repository. - See :ref:`doc_documentation_guidelines` for more details. + See :ref:`doc_contributing_to_the_documentation` for more details. Contributing translations -------------------------