Skip to content
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

Add a gdextension online documentation guide. #9966

Open
wants to merge 9 commits into
base: master
Choose a base branch
from
20 changes: 20 additions & 0 deletions tutorials/scripting/gdextension/gdextension_docs_system.rst
Original file line number Diff line number Diff line change
Expand Up @@ -172,3 +172,23 @@ Currently they supported tags for the GDExtension documentation system are:
``#ff00ff``, see :ref:`doc_bbcode_in_richtextlabel_hex_colors`).

- ``[color={code/name}]{text}[/color]``


Publishing documentation online
-------------------------------

You may want to publish an online reference for your gdextension, akin to this website. The most important step is to build ``.rst`` files from your ``.xml`` ones:
Calinou marked this conversation as resolved.
Show resolved Hide resolved

.. code-block:: none

# You'll need to have python installed for this command to work.
Calinou marked this conversation as resolved.
Show resolved Hide resolved
curl -sSL https://raw.githubusercontent.com/godotengine/godot/master/doc/tools/make_rst.py | python3 - -o "docs/classes" -l "en" doc_classes

Your ``.rst`` files will now be available in ``docs/classes/``. From here, you can use any documentation builder to create a website from them. `godot-docs <https://hosted.weblate.org/projects/godot-engine/godot-docs>`_ uses `Sphinx <https://www.sphinx-doc.org/en/master/>`_. You can use the repository as a basis to build your own documentation system. This is where you'll have to get a bit creative, but here's a rough outline of the steps involved:
Calinou marked this conversation as resolved.
Show resolved Hide resolved

1. Add `godot-docs <https://hosted.weblate.org/projects/godot-engine/godot-docs>`_ as a submodule to your ``docs/`` folder.
2. Copy over its ``conf.py``, ``index.rst``, ``.readthedocs.yaml`` files into ``/docs/``. You may later decide to copy over more of godot-docs' files into your own project, like ``_templates/layout.html``.
3. Modify these files according to your project. This mostly involves adjusting paths to point to the ``godot-docs`` subfolder, as well as strings to reflect it's your project rather than godot you're building the docs for.
Calinou marked this conversation as resolved.
Show resolved Hide resolved
4. Create an account on `readthedocs.org <http://readthedocs.org>`_. Import your project, and modify its base ``.readthedocs.yaml`` file path to ``/docs/.readthedocs.yaml``.

Once you have completed all these steps, your documentation should be available at <repo-name>.readthedocs.io.
Calinou marked this conversation as resolved.
Show resolved Hide resolved