MkDocsへの貢献

MkDocsプロジェクトへの貢献について紹介します。

MkDocsプロジェクトは、オープンソースコミュニティの開発者とユーザーからの貢献を歓迎します。貢献には、次のような方法があります。

• プルリクエストによるコードパッチ
• ドキュメントの改善
• バグレポートとパッチレビュー

利用可能なコミュニケーションチャネルについては、GitHubリポジトリのREADMEファイルを参照してください。

issueの報告

できるだけ詳細に記述してください。プラットフォームとMkDocsのバージョンをお知らせください。問題が視覚的なもの（テーマやデザインの問題など）の場合は、スクリーンショットを追加してください。エラーが発生した場合は、完全なエラーメッセージとトレースバックを含めてください。

issueレポートが以下のすべての側面に触れている場合は特に役立ちます。

1. 何を達成しようとしていますか？

2. あなたのmkdocs.yml設定（+その他の関連ファイル）は何ですか？できれば、最小限の再現可能な例に絞ってください。

3. この設定を適用したときに、何が起こると予想しましたか？

4. 代わりに何が起こり、どのようにあなたの期待と一致しませんでしたか？

開発版を試す

MkDocsの最新の開発版をインストールして試してみたい場合（ issueの修正が既に含まれている場合）、次のコマンドで実行できます。これは、新機能のフィードバックを提供したい場合や、発生したバグがgit masterで修正されていることを確認したい場合に役立ちます。virtualenv内で行うことを**強く**お勧めします。

pip install git+https://github.com/mkdocs/mkdocs.git

開発用のインストール

開発には、以下で説明するようにHatchを直接使用できます。それでもMkDocsのローカルクローンをインストールする場合は、pip install --editable .を実行できます。virtualenv内で行うことを**強く**お勧めします。

Hatchのインストール

開発に使用される主なツールはHatchです。依存関係を管理し（オンザフライで作成されるvirtualenvで）、コマンドランナーでもあります。

最初に、インストールします。理想的には、**pipx install hatch**（[pipxをインストール]した後）で分離して、またはよりよく知られている方法としてpip install hatchでインストールします。

すべてのチェックを実行する

MkDocsに必要な**すべて**のチェックを実行するには、クローンされたMkDocsリポジトリで次のコマンドを実行します。

hatch run all

これには、以下に示すすべてのチェックが含まれます。

すべてのチェックに合格する必要があります。

テストの実行

MkDocsのテストスイートを実行するには、次のコマンドを実行します。

hatch run test:test
hatch run integration:test

サポートしているすべてのPythonバージョンに対してテストを実行しようとします。そのため、一部が欠落していても心配しないでください。残りは、プルリクエストを送信するときにGitHub Actionsによって検証されます。

Pythonコードスタイル

MkDocsのコードベース内のPythonコードは、BlackとIsortを使用してフォーマットされ、Ruffを使用してリントチェックされます。これらはすべてpyproject.tomlで設定されています。

次のコマンドを使用して、これらのツールに従ってコードを自動的にチェックおよびフォーマットできます。

hatch run style:fix

コードはmypyを使用してタイプチェックされます。これもpyproject.tomlで設定されており、次のように実行できます。

hatch run types:check

その他のスタイルチェック

スペルチェックやJSスタイルなど、他にもいくつかのチェックがあります。すべてを実行するには、次のコマンドを使用します。

hatch run lint:check

MkDocs自体のドキュメント

docs/ディレクトリの下のファイルを編集した後、次のコマンドを使用してサイトをローカルでプレビューできます。

hatch run docs:serve

貢献を送信する前に、すべての「警告」を解決する必要があることに注意してください。

ドキュメントファイルもmarkdownlintによってチェックされるため、これも実行する必要があります。

hatch run lint:check

mkdocs.ymlに新しいプラグインを追加する場合、「要件」ファイルに追加する必要はありません。これは自動的に管理されるためです。

.venv/bin/pip install -r requirements/requirements-docs.txt  # Exact versions of dependencies.
.venv/bin/pip install -r $(mkdocs get-deps)  # Latest versions of all dependencies.

テーマの翻訳

テーマをお気に入りの言語にローカライズするには、テーマの翻訳のガイドに従ってください。翻訳のプルリクエストを歓迎します！

プルリクエストの送信

MkDocsに大規模なコードを貢献することを検討している場合は、最初に issue を開いて、アイデアに関する早期のフィードバックを得ることをお勧めします。

コードがレビューの準備が整ったと思ったら、フォークにプッシュしてプルリクエストを送信してください。変更が受け入れられるためには、それが新しい機能である場合、ほとんどの場合、テストとドキュメントが必要になります。

プルリクエストブランチで作業する場合
特に合意がない限り、amendよりもcommitを、rebaseよりもmergeを優先してください。強制プッシュは避けてください。そうしないと、レビュー履歴のナビゲートが非常に困難になります。最終結果については、「クリーンでない」履歴で問題ありません。ほとんどのプルリクエストはGitHubでスカッシュマージされるためです。

release-notes.mdには追加**しないで**ください。これは後で記述されます。

組み込みテーマへの変更の送信

i18nサポート付きでインストールされている場合（pip install 'mkdocs[i18n]'）、MkDocsは、テキストプレースホルダーを{% trans %}および{% endtrans %}タグで囲むことにより、Jinjaのi18n拡張機能を尊重する場合、テーマがさまざまな言語（ロケールと呼ばれる）に翻訳されることをサポートできます。

翻訳可能なテキストプレースホルダーがテーマテンプレートに追加、削除、または変更されるたびに、extract_messagesコマンドを実行して、テーマのPortable Object Template（pot）ファイルを更新する必要があります。両方の組み込みテーマのpotファイルを更新するには、次のコマンドを実行します。

pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/mkdocs/messages.pot mkdocs/themes/mkdocs
pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/readthedocs/messages.pot mkdocs/themes/readthedocs

更新されたpotファイルは、更新されたテンプレートを含むPRに含める必要があります。更新されたpotファイルにより、翻訳コントリビューターは、希望する言語に必要な翻訳を提案できます。詳細については、テーマの翻訳のガイドを参照してください。

行動規範

MkDocsプロジェクトのコードベース、 issue トラッカー、チャットルーム、メーリングリストに関わるすべての人は、PyPA行動規範に従うことが期待されています。