Contributing to the class reference

注釈

This guide also is available as a video tutorial on YouTube.

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

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

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

参考

Not sure where to start contributing? Take a look at the current class reference completion status here.

貢献する方法

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

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

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

警告

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

GitHubを使い始める

If you're new to Git and GitHub, this guide will help you get started. You'll learn to:

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

注釈

If you're new to Git, the version control system Godot uses, go through GitHub's interactive guide. You'll learn some essential vocabulary and get a sense for the tool.

フォーク Godot

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

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

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

Create a new branch to make your changes. It makes it a lot easier to sync your improvements with other docs writers. It's also easier to clean up your repository if you run into any issues with 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

You should have two: origin, your fork on GitHub that Git adds by default, and upstream, that you just added:

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 ブランチの状態にリセットします。 ローカルの変更はすべて破棄されます。 重要な変更を行うにのみ、これを実行するようにしてください。

Another option is to delete the branch you're working on, synchronize the master branch with the Godot repository, and create a new branch:

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

If you're feeling lost by now, come to our IRC channels and ask for help. Experienced Git users will give you a hand.

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

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

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

The XML files in doc/classes should then be up-to-date with current Godot Engine features. You can then check what changed using the git diff command. If there are changes to other classes than the one you are planning to document, please commit those changes first before starting to edit the template:

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を介してプルリクエストを要求できます。

警告

Although you can edit files on GitHub, it's not recommended. As hundreds of contributors work on Godot, the Git history must stay clean. Each commit should bundle all related improvements you make to the class reference, a new feature, bug fixes... When you edit from GitHub, it will create a new branch and a Pull Request every time you want to save it. If a few days pass before your changes get a review, you won't be able to update to the latest version of the repository cleanly. Also, it's harder to keep clean indents from GitHub. And they're very important in the docs.

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

クラスXMLを編集する方法

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

Edit it using your favorite text editor. If you use a code editor, make sure that it doesn't change the indent style: tabs for the XML, and 4 spaces inside BBCode-style blocks. More on that below.

生成したドキュメントで行った変更が正しいことを確認する必要がある場合は、 これ に従って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>
                Sets 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++などのコードエディタを使用して、ファイルをすばやく編集できます。検索機能を使用して、クラスを高速に検索します。

Improve formatting with BBCode style tags

Godot's class reference supports BBCode-like tags. They add nice formatting to the text. Here's the list of available tags:

タグ 効果 使用法 結果
[Class] クラスをリンクする [Sprite] へ移動。 Sprite へ移動。
[method methodname] このクラスのメソッドへのリンク [メソッド hide]を呼び出します。 hide を参照してください。
[method Class.methodname] 別のクラスのメソッドへのリンク [メソッド Spatial.hide] を呼び出します。 hide を参照してください。
[member membername] このクラスのメンバーへのリンク [メンバー scale] を取得します。 scale を取得します。
[member Class.membername] 別のクラスのメンバーへのリンク [メンバーNode2D.scale] を取得します。 scale を取得します。
[signal signalname] このクラスのシグナルへのリンク [シグナル renamed] を発信します。 renamed を発信します。
[signal Class.signalname] 別のクラスのシグナルへのリンク [シグナル Node.renamed] を発信します。 renamed を発信します。
[b] [/b] 太字 部分的な [b]bold[/b] テキスト。 部分的な bold テキスト。
[i] [/i] 斜体 部分的な [i]italic[/i] テキスト。 部分的な italic テキスト。
[code] [/code] モノスペース 部分的な [code]monospace[/code] テキスト。 部分的な monospace テキスト。
[kbd] [/kbd] キーボードショートカット Some [kbd]Ctrl + C[/kbd] key. Some Ctrl + C key.
[codeblock] [/codeblock] マルチラインプリフォーマットブロック 下記参照。 下記参照。

事前にフォーマットされたコードブロックには [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())

To denote important information, add a paragraph starting with "[b]Note:[/b]" at the end of the description:

[b]Note:[/b] Only available when using the GLES2 renderer.

To denote crucial information that could cause security issues or loss of data if not followed carefully, add a paragraph starting with "[b]Warning:[/b] at the end of the description:

[b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server.

For deprecated properties, add a paragraph starting with "[i]Deprecated.[/i]". Notice the use of italics instead of bold:

[i]Deprecated.[/i] This property has been replaced by [member other_property].

In all the paragraphs described above, make sure the punctuation is part of the BBCode tags for consistency.

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

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

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

ローカライズ

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

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

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