クラスリファレンスへの貢献

Godotには、ゲームの開発に役立つ多くのノードとシングルトンが付属しています。各クラスは、クラスリファレンス に記載されています。このリファレンスは、エンジンを学習している人にとって不可欠です。オンラインとエンジンの両方で利用できます。

しかし、それは不完全です。メソッド、変数、シグナルの中には、説明がないものもあります。最近のリリースで変更され、更新が必要なものもあります。開発者だけでリファレンス全体を作成することはできません。Godotには、あなたと私たちのすべての貢献が必要です。

重要:大規模な変更や大きな貢献を計画している場合は、問題(または既存の1のコメント)を作成して他の人に知らせ、同じ作業を開始しないようにすることをお勧めします。

注釈

このガイドは、YouTubeのビデオチュートリアル <https://www.youtube.com/watch?v=5jeHXxeX-JY>`_ から入手できます。

貢献する方法

クラスリファレンスは、GodotのGitHubリポジトリにある次のXMLファイルにあります: ドキュメント/クラス/

クラスリファレンスを更新するには、次の5つの手順があります(以下の完全なガイド):

  1. フォーク Godotのリポジトリ
  2. コンピュータでフォークのクローンを作成する
  3. doc/classes/ でクラス ファイルを編集してドキュメントを作成する
  4. 変更をコミットし、フォークにプッシュする
  5. Godotリポジトリでプルリクエストを行う

警告

APIリファレンスを編集するには、常にこれらのXMLファイルを使用してください。godot-docsリポジトリでホストされているオンラインドキュメントで生成された.rstファイルを編集しないでください。

GitHubを使い始める

GitとGitHubを使用するのが初めての場合は、このガイドを参考にしてください。次の方法について学習します:

  • フォークとクローンGodotのリポジトリ
  • 他の貢献者とあなたのフォークを最新の状態に保つ
  • プルリクエストを作成して、公式ドキュメントで改善が終了できるようにします

注釈

Godotが使用するバージョン管理システムであるgitを初めて使用する場合は、GitHubのインタラクティブガイドをご覧ください。 いくつかの重要な語彙を学び、ツールの意味が理解できるようになります。

フォーク Godot

Godotエンジンを独自のGitHubリポジトリにフォークします。

コンピュータ上にリポジトリのクローンを作成します:

git clone https://github.com/your_name/godot.git

新しいブランチを作成して、変更を加えます。 改善点を他のドキュメントライターと同期するのがはるかに簡単になり、gitに問題がある場合はリポジトリをクリーンアップするのが簡単になります。

git checkout -b your-new-branch-name

新しいブランチは、APIドキュメントの作成を開始するまで、masterブランチと同じです。 doc/ フォルダには、クラス参照が表示されます。

ローカルのクローンを最新の状態に保つ方法

他の人々もGodotのドキュメントに貢献しています。ローカルリポジトリではその貢献が反映されない為、能動的に同期する必要があります。特に、作業中に他の貢献者がクラス参照を更新した場合には注意してください。

まず、 upstream のgitリモートを追加します。「Remotes」 は、新しいファイルをダウンロードできるオンライン・リポジトリへのリンクです。

git remote add upstream https://github.com/godotengine/godot

すべてのリモート サーバーの一覧を次のように確認できます:

git remote -v

githubのフォークである origin と、その git がデフォルトで追加するもの、そして追加したばかりの upstream の2つが必要です:

origin  https://github.com/your_name/godot.git (fetch)
origin  https://github.com/your_name/godot.git (push)
upstream        https://github.com/godotengine/godot.git (fetch)
upstream        https://github.com/godotengine/godot.git (push)

ブランチをアップストリームリポジトリの状態に同期するたびに、次のように入力します:

git pull --rebase upstream master

このコマンドは、最初に fetch を行うか、Godotリポジトリの最新バージョンをダウンロードします。次に、ローカルの変更が再度適用されます。

ローカルブランチに残したくない変更を加えた場合は、代わりに次のコマンドを使用します:

git fetch upstream
git reset --hard upstream master

警告:上記のコマンドは、ブランチを upstream master ブランチの状態にリセットします。 ローカルの変更はすべて破棄されます。 重要な変更を行うにのみ、これを実行するようにしてください。

もう1つのオプションは、作業中のブランチを削除し、masterブランチをGodotリポジトリと同期し、新しいブランチを作成することです:

git checkout master
git branch -d your-new-branch-name
git pull --rebase upstream master
git checkout -b your-new-branch-name

もし今、迷っているなら、IRCチャンネルに来て助けを求めてください。経験豊富なgitユーザがお手伝いします。

ドキュメントテンプレートの更新

ソースコードでクラスが変更されると、ドキュメントテンプレートが古くなる可能性があります。最新バージョンを編集していることを確認するには、まずGodotをコンパイルする必要があります (ビルドシステムの説明ページに従ってから)。次のコマンドを実行します (64ビットLinuxを想定):

./bin/godot.x11.tools.64 --doctool .

ドキュメント/クラスのxmlファイルは、現在のGodot エンジン機能を使用して最新の状態にする必要があります。その後、 git diff コマンドを使用して変更された内容を確認できます。ドキュメント化するクラス以外のクラスに変更がある場合は、テンプレートの編集を開始する前に、まずこれらの変更をコミットしてください:

git add doc/classes/*.xml
git commit -m "Sync classes reference template with current code base"

これで、このファイルを編集して追加する準備が整いました。

注意:最近、別の貢献者がこれを行った場合は、これらの手順を強制的に実行する必要はありません(編集しようとしているクラスが最近変更されたことがわかっている場合を除きます)。

変更のプルをプッシュしてリクエストする

変更が完了したら、GitHubリポジトリで変更をプッシュします:

git add doc/classes/<edited_file>.xml
git commit -m "Explain your modifications."
git push

完了したら、GodotフォークのGitHubUIを介してプルリクエストを要求できます。

警告

GitHubでファイルを編集できますが、お勧めしません。 何百人もの貢献者がGodotで作業しているので、gitの履歴はクリーンなままでなければなりません。 各コミットは、クラス参照に加えた関連するすべての改善、新機能、バグ修正をバンドルする必要があります... GitHubから編集すると、保存するたびに新しいブランチとプルリクエストが作成されます。 変更をレビューする前に数日が経過すると、リポジトリの最新バージョンに完全に更新できなくなります。 また、GitHubのインデントをきれいに保つことは困難です。 そして、それらはドキュメントで非常に重要です。

TL;DR:自分が何をしているか正確にわからない場合は、GitHubからファイルを編集しないでください。

クラスXMLを編集する方法

選択したクラスのファイルを doc/class/ で編集して、クラスリファレンスを更新します。フォルダには、各クラスのXMLファイルが含まれています。XMLには、クラス参照に含まれる定数とメソッドが一覧表示されます。GodotはXMLを自動的に生成して更新します。

お気に入りのテキストエディタを使用して編集します。コードエディタを使用する場合は、インデントスタイル(XMLのタブ、およびBBcodeスタイルのブロック内の4つのスペース) が変更されないようにしてください。詳しくは以下をご覧ください。

生成したドキュメントで行った変更が正しいことを確認する必要がある場合は、 これ に従ってGodotをビルドし、エディタを実行して変更したページのヘルプを開きます。

クラスリファレンスの書き方

各クラスには、簡単な説明と長い説明があります。 簡単な説明は常にページの上部にあり、完全な説明はメソッド、変数、定数のリストの下にあります。 メソッド、メンバー変数、定数、およびシグナルは、個別のカテゴリーまたはXMLノードにあります。 それぞれについて、Godotのソースコードでどのように機能するかを学習し、<description>を入力します。

私たちの仕事は、これらのマークの間に不足しているテキストを追加することです:

  • <description></description>
  • <brief_description></brief_description>
  • <constant></constant>
  • <method></method>
  • <member></member>
  • <signal></signal>

明確でシンプルな言葉で書きます。常に書き込みガイドラインに従って説明を短く読みやすくします。説明に空の行を残さないようにしてください

XMLでのクラスの外観は次のようにします:

<class name="Node2D" inherits="CanvasItem" category="Core">
    <brief_description>
    Base node for 2D system.
    </brief_description>
    <description>
    Base node for 2D system. Node2D contains a position, rotation and scale, which is used to position and animate. It can alternatively be used with a custom 2D transform ([Matrix32]). A tree of Node2Ds allows complex hierarchies for animation and positioning.
    </description>
    <methods>
        <method name="set_pos">
            <argument index="0" name="pos" type="Vector2">
            </argument>
            <description>
            Set the position of the 2d node.
            </description>
        </method>
        [...]
        <method name="edit_set_pivot">
            <argument index="0" name="arg0" type="Vector2">
            </argument>
            <description>
            </description>
        </method>
    </methods>
    <members>
        <member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position" brief="">
        </member>
        [...]
        <member name="z_as_relative" type="bool" setter="set_z_as_relative" getter="is_z_relative" brief="">
        </member>
    </members>
    <constants>
    </constants>
</class>

Vim、Atom、Code、Notepad++などのコードエディタを使用して、ファイルをすばやく編集できます。検索機能を使用して、クラスを高速に検索します。

BBcodeスタイルタグを使用した書式設定を改善する

Godotのクラス参照は、BBcodeのようなタグをサポートしています。これらは、テキストに素敵な書式を追加します。使用可能なタグの一覧を次に表示します:

タグ 効果 使用法 結果
[Class] クラスをリンクする [Sprite] を動かす。 class_sprite を動かす。
[method methodname] このクラスのメソッドへのリンク Call [method hide]. See hide.
[method Class.methodname] 別のクラスのメソッドへのリンク Call [method Spatial.hide]. See hide.
[member membername] このクラスのメンバーへのリンク Get [member scale]. Get scale.
[member Class.membername] 別のクラスのメンバーへのリンク Get [member Node2D.scale]. Get scale.
[signal signalname] このクラスのシグナルへのリンク Emit [signal renamed]. Emit renamed.
[signal Class.signalname] 別のクラスのシグナルへのリンク Emit [signal Node.renamed]. Emit renamed.
[b] [/b] 太字 Some [b]bold[/b] text. Some bold text.
[i] [/i] 斜体 Some [i]italic[/i] text. Some italic text.
[code] [/code] モノスペース Some [code]monospace[/code] text. Some monospace text.
[codeblock] [/codeblock] マルチラインプリフォーマットブロック See below. See below.

事前にフォーマットされたコードブロックには [codeblock] を使用します。[codeblock] 内では、インデントには常に 4つのスペース を使用します(パーサーはタブを削除します)。例:

[codeblock]
func _ready():
    var sprite = get_node("Sprite")
    print(sprite.get_pos())
[/codeblock]

次のように表示されます:

func _ready():
    var sprite = get_node("Sprite")
    print(sprite.get_pos())

この方法が何をするのかわかりません!

大丈夫ですよ。そのままにしておき、変更のプルを要求したときにスキップしたメソッドをリストします。他の人が担当します。

GitHubのGodotのソースコードでメソッドの実装を見ることができます。 また、疑問がある場合は、Q&A WebサイトおよびIRC(freenode、#godotengine)でお気軽にお問い合わせください。

ローカライズ

ドキュメントは、Hosted Weblate で任意の言語に翻訳できます。

翻訳された文字列は、godot-docs-l10n リポジトリのドキュメントメンテナーによって手動で同期されます。

完成度の高い言語には、独自のローカライズされたReadTheDocsのインスタンスがあります。新しい言語が独自のインスタンスを取得するのに十分であると思われる場合は、godot-docs-l10n リポジトリでissueをオープンします。