|
@@ -449,54 +449,87 @@ There are several steps in order to setup custom docs for the module:
|
|
|
1. Make a new directory in the root of the module. The directory name can be
|
|
|
anything, but we'll be using the ``doc_classes`` name throughout this section.
|
|
|
|
|
|
-2. Append the following code snippet to ``config.py``:
|
|
|
+2. Now, we need to edit ``config.py``, add the following snippet:
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
- def get_doc_classes():
|
|
|
- return [
|
|
|
- "ClassName",
|
|
|
- ]
|
|
|
+ def get_doc_path():
|
|
|
+ return "doc_classes"
|
|
|
|
|
|
- def get_doc_path():
|
|
|
- return "doc_classes"
|
|
|
+ def get_doc_classes():
|
|
|
+ return [
|
|
|
+ "Summator",
|
|
|
+ ]
|
|
|
+
|
|
|
+The ``get_doc_path()`` function is used by the build system to determine
|
|
|
+the location of the docs. In this case, they will be located in the
|
|
|
+``modules/summator/doc_classes`` directory. If you don't define this,
|
|
|
+the doc path for your module will fall back to the main ``doc/classes``
|
|
|
+directory.
|
|
|
|
|
|
The ``get_doc_classes()`` method is necessary for the build system to
|
|
|
-know which documentation classes of the module must be merged, since the module
|
|
|
-may contain several classes. Replace ``ClassName`` with the name of the class
|
|
|
-you want to write documentation for. If you need docs for more than one class,
|
|
|
-append those as well.
|
|
|
+know which registered classes belong to the module. You need to list all of your
|
|
|
+classes here. The classes that you don't list will end up in the
|
|
|
+main ``doc/classes`` directory.
|
|
|
|
|
|
-The ``get_doc_path()`` method is used by the build system to determine
|
|
|
-the location of the docs. In our case, they will be located in the ``doc_classes``
|
|
|
-directory.
|
|
|
+.. tip::
|
|
|
|
|
|
-3. Run command:
|
|
|
+ You can use git to check if you have missed some of your classes by checking the
|
|
|
+ untracked files with ``git status``. For example::
|
|
|
|
|
|
- .. code-block:: shell
|
|
|
+ user@host:~/godot$ git status
|
|
|
|
|
|
- godot --doctool <path>
|
|
|
+ Example output::
|
|
|
|
|
|
-This will dump the engine API reference to the given ``<path>`` in XML format.
|
|
|
-Notice that you'll need to configure your ``PATH`` to locate Godot's executable,
|
|
|
-and make sure that you have write access rights. If not, you might encounter an
|
|
|
-error similar to the following:
|
|
|
+ Untracked files:
|
|
|
+ (use "git add <file>..." to include in what will be committed)
|
|
|
+
|
|
|
+ doc/classes/MyClass2D.xml
|
|
|
+ doc/classes/MyClass4D.xml
|
|
|
+ doc/classes/MyClass5D.xml
|
|
|
+ doc/classes/MyClass6D.xml
|
|
|
+ ...
|
|
|
+
|
|
|
|
|
|
-.. code-block:: console
|
|
|
+3. Now we can generate the documentation:
|
|
|
|
|
|
- ERROR: Can't write doc file: docs/doc/classes/@GDScript.xml
|
|
|
- At: editor/doc/doc_data.cpp:956
|
|
|
+We can do this via running Godot's doctool i.e. ``godot --doctool <path>``,
|
|
|
+which will dump the engine API reference to the given ``<path>`` in XML format.
|
|
|
+
|
|
|
+In our case we'll point it to the root of the cloned repository. You can point it
|
|
|
+to an another folder, and just copy over the files that you need.
|
|
|
+
|
|
|
+Run command:
|
|
|
+
|
|
|
+ ::
|
|
|
|
|
|
-4. Get generated doc file from ``godot/doc/classes/ClassName.xml``
|
|
|
+ user@host:~/godot/bin$ ./bin/<godot_binary> --doctool .
|
|
|
|
|
|
-5. Copy this file to ``doc_classes``, optionally edit it, then compile the engine.
|
|
|
+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.
|
|
|
|
|
|
-The build system will fetch the documentation files from the ``doc_classes`` directory
|
|
|
-and merge them with the base types. Once the compilation process is finished,
|
|
|
-the docs will become accessible within the engine's built-in documentation system.
|
|
|
+Edit the file(s) following :ref:`doc_updating_the_class_reference` and recompile the engine.
|
|
|
+
|
|
|
+Once the compilation process is finished, the docs will become accessible within
|
|
|
+the engine's built-in documentation system.
|
|
|
|
|
|
In order to keep documentation up-to-date, all you'll have to do is simply modify
|
|
|
-one of the ``ClassName.xml`` files and recompile the engine from now on.
|
|
|
+one of the XML files and recompile the engine from now on.
|
|
|
+
|
|
|
+If you change your module's API, you can also re-extract the docs, they will contain
|
|
|
+the things that you previously added. Of course if you point it to your godot
|
|
|
+folder, make sure you don't lose work by extracting older docs from an older engine build
|
|
|
+on top of the newer ones.
|
|
|
+
|
|
|
+Note that if you don't have write access rights to your supplied ``<path>``,
|
|
|
+you might encounter an error similar to the following:
|
|
|
+
|
|
|
+.. code-block:: console
|
|
|
+
|
|
|
+ ERROR: Can't write doc file: docs/doc/classes/@GDScript.xml
|
|
|
+ At: editor/doc/doc_data.cpp:956
|
|
|
+
|
|
|
|
|
|
.. _doc_custom_module_icons:
|
|
|
|