Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Adicionando documentação

Nota

Adicionar documentação para GDExtensions só é possível a partir do Godot 4.3.

O sistema de documentação da GDExtension funciona de maneira semelhante à documentação embutida do motor: ele usa arquivos XML (um por classe) para documentar os construtores, propriedades, métodos, constantes, sinais expostos e muito mais.

Para começar, identifique a pasta do projeto de teste do seu projeto, que deve conter um projeto Godot com a sua extensão instalada e funcionando. Se você estiver usando o godot-cpp-template, seu projeto GDExtension já possui uma pasta project. Como alternativa, você pode adicionar uma seguindo as etapas descritas em Primeiros passos. Dentro da pasta project, execute o seguinte comando no terminal:

# Replace "godot" with the full path to a Godot editor binary
# if Godot is not installed in your `PATH`.
godot --doctool ../ --gdextension-docs

Esse comando instrui o Godot a gerar a documentação por meio dos comandos --doctool e --gdextension-docs. O argumento ../ especifica o caminho base da sua GDExtension.

Depois de executar esse comando, você deverá encontrar os arquivos XML para as suas classes registradas da GDExtension dentro da pasta doc_classes no seu projeto GDExtension. Você poderia editá-los agora, mas para este tutorial, os arquivos vazios serão suficientes.

Agora que você tem arquivos XML contendo a sua documentação, o próximo passo é incluí-los no binário da sua GDExtension. Assumindo que você está usando o SCons como seu sistema de compilação, você pode adicionar as seguintes linhas ao seu arquivo SConstruct. Se você estiver usando o godot-cpp-template, seu arquivo já contém o código para isso.

if env["target"] in ["editor", "template_debug"]:
    doc_data = env.GodotCPPDocData("src/gen/doc_data.gen.cpp", source=Glob("doc_classes/*.xml"))
    sources.append(doc_data)

A instrução if evita a adição da documentação em compilações de lançamento (release) da sua GDExtension, onde ela não é necessária. O SCons então carrega todos os arquivos XML dentro do diretório doc_classes e anexa os alvos resultantes à array sources, para serem incluídos na compilação da sua GDExtension.

Após a compilação, inicie o seu projeto Godot novamente. Você pode abrir a documentação de uma das suas classes de extensão usando Ctrl + Clique em um nome de classe no editor de scripts, ou encontrando-a na caixa de diálogo de ajuda do Editor. Se tudo correu bem, você deve ver algo assim:

../../../_images/gdextension_docs_generation.webp

Escrevendo e estilizando documentação

O formato dos arquivos XML de referência de classe é o mesmo utilizado pelo Godot. Ele está documentado em Introdução à referência de classe.

Se você está procurando dicas para escrever documentação de alta qualidade, sinta-se à vontade para consultar as diretrizes de documentação do Godot.

Publicando documentação online

Você pode querer publicar uma referência online para a sua GDExtension, semelhante a este site. O passo mais importante é gerar arquivos reStructuredText (.rst) a partir do seu arquivo XML de referência de classe:

# You need a version.py file, so download it first.
curl -sSLO https://raw.githubusercontent.com/godotengine/godot/refs/heads/master/version.py

# Edit version.py according to your project before proceeding.
# Then, run the rst generator. You'll need to have Python installed for this command to work.
curl -sSL https://raw.githubusercontent.com/godotengine/godot/master/doc/tools/make_rst.py | python3 - -o "docs/classes" -l "en" doc_classes

Seus arquivos .rst estarão agora disponíveis em docs/classes/. A partir daqui, você pode usar qualquer gerador de documentação que suporte a sintaxe reStructuredText para criar um site a partir deles.

O godot-docs usa o Sphinx. Você pode usar o repositório como base para construir o seu próprio sistema de documentação. O guia a seguir descreve os passos básicos, mas eles não são exaustivos: você precisará de um pouco de percepção pessoal para fazê-lo funcionar.

  1. Adicione godot-docs como um submódulo à sua pasta docs/.

  2. Copie os arquivos conf.py, index.rst e .readthedocs.yaml dele para dentro de /docs/. Mais tarde, você pode decidir copiar e editar mais arquivos do godot-docs, como _templates/layout.html.

  3. Modifique esses arquivos de acordo com o seu projeto. Isso envolve principalmente ajustar os caminhos para apontar para a subpasta godot-docs, bem como alterar as strings para refletir que você está construindo a documentação para o seu projeto, e não para o Godot.

  4. Crie uma conta no site readthedocs.org. Importe o seu projeto e modifique o caminho do arquivo base .readthedocs.yaml para /docs/.readthedocs.yaml.

Once you have completed all these steps, your documentation should be available at <repository-name>.readthedocs.io.