Skip to content

Add details about generating XML files from documentation comments #10908

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 21 additions & 2 deletions tutorials/scripting/gdscript/gdscript_documentation_comments.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ members of a script. There are two differences between a normal comment and a do
comment. Firstly, a documentation comment should start with double hash symbols
``##``. Secondly, it must immediately precede a script member, or for script descriptions,
be placed at the top of the script. If an exported variable is documented,
its description is used as a tooltip in the editor. This documentation can be
generated as XML files by the editor.
its description is used as a tooltip in the editor. The editor can also export XML files
of this documentation, see `Generating XML files`_ for details on this.

Documenting a script
--------------------
Expand Down Expand Up @@ -355,3 +355,22 @@ the ``lang`` attribute. Currently supported options are:
- ``[codeblock lang=text]`` disables syntax highlighting;
- ``[codeblock lang=gdscript]`` highlights GDScript syntax;
- ``[codeblock lang=csharp]`` highlights C# syntax (only in .NET version).

Generating XML files
--------------------

The editor can generate XML files from your documentation comments, which can be useful to create
an online documentation. To generate the XML files, you can execute the following command from your
project's root folder:

::

godot --doctool <destination> --gdscript-docs <path>

The XML files will be generated in the ``<destination>`` folder, or ``docs`` if omitted.
The target ``<path>`` specifies which scripts will be included, and Godot will recursively generate
XML files for all scripts in this folder and all subfolders.

.. warning::

``<path>`` must start with ``res://``, otherwise Godot will not be able to find scripts!