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...

문서의 구조

참고

GDExtensions에 대한 문서 추가는 Godot 4.3 이상에서만 가능합니다.

GDExtension 문서 시스템은 내장 엔진 문서와 비슷한 방식으로 작동합니다. :ref:`XML 파일 <doc_class_reference_primer>`(클래스당 하나)를 사용하여 노출된 생성자, 속성, 메서드, 상수, 시그널 등을 문서화합니다.

시작하려면 확장 기능이 설치되어 작동하는 Godot 프로젝트를 포함해야 하는 프로젝트의 테스트 프로젝트 폴더를 식별하세요. godot-cpp-template <https://github.com/godotengine/godot-cpp-template>`__을 사용하는 경우 GDExtension 프로젝트에 이미 ``project` 폴더가 있습니다. 또는 doc_godot_cpp_getting_started`에 설명된 단계에 따라 추가할 수 있습니다. ``project` 폴더 내에서 다음 터미널 명령을 실행합니다.

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

이 명령은 Godot에게 --doctool 및 --gdextension-docs 명령을 통해 문서를 생성하도록 지시합니다. ../ 인수는 GDExtension의 기본 경로를 지정합니다.

이 명령을 실행한 후 GDExtension 프로젝트의 doc_classes 폴더 내에서 등록된 GDExtension 클래스에 대한 XML 파일을 찾아야 합니다. 지금 편집할 수 있지만 이 튜토리얼에서는 빈 파일이면 충분합니다.

이제 문서가 포함된 XML 파일이 있으므로 다음 단계는 이를 GDExtension 바이너리에 포함하는 것입니다. SCons를 빌드 시스템으로 사용한다고 가정하면 SConstruct 파일에 다음 줄을 추가할 수 있습니다. `godot-cpp-template <https://github.com/godotengine/godot-cpp-template>`__을 사용하는 경우 파일에 이미 이에 대한 코드가 포함되어 있습니다.

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)

if 문은 필요하지 않은 GDExtension의 릴리스 빌드에 문서를 추가하는 것을 방지합니다. 그런 다음 SCons는 doc_classes 디렉터리 내의 모든 XML 파일을 로드하고 결과 대상을 sources 배열에 추가하여 GDExtension 빌드에 포함시킵니다.

빌드 후 Godot 프로젝트를 다시 시작하세요. 스크립트 편집기에서 클래스 이름에 :kbd:`Ctrl + Click`을 사용하거나 편집기 도움말 대화 상자에서 찾아서 확장 클래스 중 하나의 문서를 열 수 있습니다. 모든 것이 잘 진행되었다면 다음과 같은 내용이 표시됩니다.

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

문서의 구조

The format of the class reference XML files is the same as the one used by Godot. It is documented in 클래스 참조 입문.

엔진 소스 작업 방법, 문서 편집 방법 및 기여 방법에 대한 설명은 기여자를 위한 문서에 수록되어 있습니다.

문서의 구조

이 웹사이트와 유사하게 GDExtension에 대한 온라인 참조를 게시할 수 있습니다. 가장 중요한 단계는 XML 클래스 참조에서 reStructuredText(.rst) 파일을 빌드하는 것입니다.

# 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

이제 .rst 파일을 ``docs/classes/``에서 사용할 수 있습니다. 여기에서 reStructuredText 구문을 지원하는 문서 빌더를 사용하여 웹 사이트를 만들 수 있습니다.

`godot-docs <https://github.com/godotengine/godot-docs>`_은 `Sphinx <https://www.sphinx-doc.org/en/master/>`_을 사용합니다. 저장소를 기초로 사용하여 자신만의 문서 시스템을 구축할 수 있습니다. 다음 가이드에서는 기본 단계를 설명하지만 완전하지는 않습니다. 이를 작동하려면 약간의 개인적인 통찰력이 필요합니다.

  1. godot-cpp 저장소 의 사본.

  2. conf.py, index.rst, .readthedocs.yaml 파일을 ``/docs/``에 복사합니다. 나중에 ``_templates/layout.html``와 같은 godot-docs 파일을 더 많이 복사하고 편집하기로 결정할 수도 있습니다.

  3. 프로젝트에 따라 이 파일을 수정하세요. 여기에는 주로 godot-docs 하위 폴더를 가리키도록 경로를 조정하는 것과 문서를 작성하는 Godot가 아닌 프로젝트를 반영하는 문자열이 포함됩니다.

  4. 만들기 readthedocs.org <http://readthedocs.org>`_의 계정입니다. 프로젝트를 가져오고 기본 `.readthedocs.yaml`` 파일 경로를 ``/docs/.readthedocs.yaml``로 수정합니다.

이러한 단계를 모두 완료하면 ``<repo-name>.readthedocs.io``에서 문서를 사용할 수 있습니다.