Merge pull request #1005 from Xrayez/module-custom-docs

Add section about writing custom documentation for modules

development/cpp/custom_modules_in_cpp.rst

@@ -340,6 +340,68 @@ shared module as target in the scons command:
 
     user@host:~/godot$ scons summator_shared=yes bin/summator.x11.tools.64.so
 
+Writing custom documentation
+----------------------------
+
+Writing documentation may seem like a boring task, but it is highly recommended
+to document your newly created module in order to make it easier for users to
+benefit from it. Not to mention that the code you've written one year ago may
+become indistinguishable from the code that was written by someone else, so be
+kind to your future self!
+
+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``:
+
+   .. code:: python
+
+       def get_doc_classes():
+           return [
+               "ClassName",
+           ]
+
+       def get_doc_path():
+           return "doc_classes"
+
+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.
+
+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.
+
+3. Run command:
+
+   ::
+
+      godot --doctool <path>
+
+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:
+
+.. code-block:: console
+
+    ERROR: Can't write doc file: docs/doc/classes/@GDScript.xml
+       At: editor/doc/doc_data.cpp:956
+
+4. Get generated doc file from ``godot/doc/classes/ClassName.xml``
+
+5. Copy this file to ``doc_classes``, optionally edit it, then compile the engine.
+
+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.
+
+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.
 
 Summing up
 ----------