コンテンツへスキップ

開発 - 貢献する

まず、FastAPIを助け、助けを得る基本的な方法を確認したいかもしれません。

開発中

fastapiリポジトリをクローン済みで、コードを深く掘り下げたい場合は、環境をセットアップするためのガイドラインをいくつか示します。

仮想環境

fastapiの内部コード用の仮想環境を作成してアクティブ化する手順に従ってください。

pipを使用して要件をインストールする

環境をアクティブ化した後、必要なパッケージをインストールします。

$ pip install -r requirements.txt

---> 100%

これにより、すべての依存関係とローカルのFastAPIがローカル環境にインストールされます。

ローカルFastAPIを使用する

FastAPIをインポートして使用するPythonファイルを作成し、それをローカル環境のPythonで実行すると、クローンしたローカルのFastAPIソースコードが使用されます。

そして、そのローカルのFastAPIソースコードを更新し、そのPythonファイルを再度実行すると、編集したばかりのFastAPIの最新バージョンが使用されます。

このようにして、変更をテストするためにローカルバージョンを「インストール」する必要はありません。

技術的な詳細

これは、pip install fastapiを直接実行するのではなく、この付属のrequirements.txtを使用してインストールした場合にのみ発生します。

これは、requirements.txtファイル内で、FastAPIのローカルバージョンが「編集可能」モード（-eオプション付き）でインストールされるようにマークされているためです。

コードをフォーマットする

すべてのコードをフォーマットしてクリーンアップするスクリプトを実行できます。

$ bash scripts/format.sh

これにより、すべてのインポートも自動的にソートされます。

テスト

すべてのコードをテストし、HTMLでカバレッジレポートを生成するためにローカルで実行できるスクリプトがあります。

$ bash scripts/test-cov-html.sh

このコマンドは./htmlcov/ディレクトリを生成します。ブラウザで./htmlcov/index.htmlファイルを開くと、テストでカバーされているコード領域をインタラクティブに探索し、不足している領域があるかどうかを確認できます。

ドキュメント

まず、すべての要件がインストールされるように、上記のように環境をセットアップしていることを確認してください。

ドキュメントをライブ表示

ローカル開発中、サイトをビルドし、変更をチェックしてライブリロードするスクリプトがあります。

$ python ./scripts/docs.py live

<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
<span style="color: green;">[INFO]</span> Start watching changes
<span style="color: green;">[INFO]</span> Start detecting changes

ドキュメントはhttp://127.0.0.1:8008で提供されます。

これにより、ドキュメント/ソースファイルを編集し、変更をライブで確認できます。

ヒント

または、スクリプトが行うのと同じ手順を手動で実行することもできます。

言語ディレクトリに移動します。英語の主要なドキュメントはdocs/en/にあります。

$ cd docs/en/

次に、そのディレクトリでmkdocsを実行します。

$ mkdocs serve --dev-addr 127.0.0.1:8008

Typer CLI (オプション)

ここでの手順は、./scripts/docs.pyにあるスクリプトをpythonプログラムで直接使用する方法を示しています。

しかし、Typer CLIを使用することもでき、補完をインストールすると、ターミナルでコマンドのオートコンプリートが利用できます。

Typer CLIをインストールしている場合は、以下のコマンドで補完をインストールできます。

$ typer --install-completion

zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.

ドキュメントの構造

ドキュメントはMkDocsを使用しています。

そして、./scripts/docs.pyには翻訳を処理するための追加ツール/スクリプトがあります。

ヒント

./scripts/docs.pyのコードを見る必要はなく、コマンドラインで使用するだけです。

すべてのドキュメントは、./docs/en/ディレクトリ内のMarkdown形式です。

多くのチュートリアルにはコードブロックが含まれています。

ほとんどの場合、これらのコードブロックはそのまま実行できる完全なアプリケーションです。

実際、これらのコードブロックはMarkdown内に書かれているのではなく、./docs_src/ディレクトリにあるPythonファイルです。

そして、これらのPythonファイルは、サイト生成時にドキュメントにインクルード/インジェクトされます。

テスト用ドキュメント

ほとんどのテストは、実際にはドキュメント内のサンプルソースファイルに対して実行されます。

これにより、次のことが確認されます。

  • ドキュメントは最新の状態です。
  • ドキュメントの例はそのまま実行できます。
  • ほとんどの機能はドキュメントでカバーされており、テストカバレッジによって保証されています。

アプリとドキュメントを同時に実行

たとえば、次のコマンドで例を実行する場合

$ fastapi dev tutorial001.py

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Uvicornはデフォルトでポート8000を使用するため、ポート8008のドキュメントと競合することはありません。

翻訳

翻訳へのご協力は大変歓迎いたします！コミュニティの助けなしには実現できません。🌎 🚀

翻訳にご協力いただくための手順を以下に示します。

ヒントとガイドライン

  • お使いの言語の既存のプルリクエストを確認してください。プルリクエストは、お使いの言語のラベルでフィルタリングできます。たとえば、スペイン語の場合、ラベルはlang-esです。

  • それらのプルリクエストをレビューし、変更を要求するか、承認します。私が話せない言語については、マージする前に数人のレビューを待ちます。

ヒント

既存のプルリクエストにコメントを追加して、変更の提案を行うことができます。

承認または変更を要求するためのプルリクエストレビューの追加に関するドキュメントを確認してください。

  • お使いの言語の翻訳を調整するためのGitHub Discussionがあるかどうかを確認してください。購読すると、レビューすべき新しいプルリクエストがある場合に、自動コメントがディスカッションに追加されます。

  • ページを翻訳する場合は、翻訳されたページごとに1つのプルリクエストを追加してください。これにより、他の人がレビューしやすくなります。

  • 翻訳したい言語の2文字コードを確認するには、ISO 639-1コードのリストの表を使用できます。

既存の言語

スペイン語のように、一部のページにすでに翻訳がある言語のページを翻訳したいとします。

スペイン語の場合、2文字コードはesです。したがって、スペイン語の翻訳ディレクトリはdocs/にあります。

ヒント

メインの（「公式」）言語は英語で、docs/en/にあります。

次に、スペイン語のドキュメントのライブサーバーを実行します。

// Use the command "live" and pass the language code as a CLI argument
$ python ./scripts/docs.py live es

<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
<span style="color: green;">[INFO]</span> Start watching changes
<span style="color: green;">[INFO]</span> Start detecting changes

ヒント

または、スクリプトが行うのと同じ手順を手動で実行することもできます。

言語ディレクトリに移動します。スペイン語の翻訳はdocs/にあります。

$ cd docs/

次に、そのディレクトリでmkdocsを実行します。

$ mkdocs serve --dev-addr 127.0.0.1:8008

これで、http://127.0.0.1:8008にアクセスして、変更をライブで確認できます。

すべての言語にすべてのページがあることがわかります。しかし、一部のページは翻訳されておらず、上部に翻訳が不足していることに関する情報ボックスが表示されます。

次に、Featuresセクションの翻訳を追加したいとします。

  • 以下のファイルをコピーします。
docs/en/docs/features.md
  • それをまったく同じ場所に貼り付けますが、翻訳したい言語の場合、例えば、
docs/docs/features.md

ヒント

パスとファイル名で唯一の変更は、言語コードがenからesに変更されていることに注意してください。

ブラウザにアクセスすると、新しいセクションが表示され（上部の情報ボックスがなくなっています）。🎉

これで、ファイルを保存しながら、すべてを翻訳してどのように見えるかを確認できます。

これらのページは翻訳しないでください

🚨 翻訳しないでください

  • reference/以下のファイル
  • release-notes.md
  • fastapi-people.md
  • external-links.md
  • newsletter.md
  • management-tasks.md
  • management.md
  • contributing.md

これらのファイルの一部は頻繁に更新され、翻訳は常に遅れてしまうか、英語のソースファイルからメインコンテンツを取り込んでいるなどの理由があります。

新しい言語

まだ翻訳されていない、あるいは一部のページすら翻訳されていない言語の翻訳を追加したいとします。

クレオール語の翻訳を追加したいとしますが、ドキュメントにはまだありません。

上記のリンクを確認すると、「クレオール語」のコードはhtです。

次のステップは、新しい翻訳ディレクトリを生成するスクリプトを実行することです。

// Use the command new-lang, pass the language code as a CLI argument
$ python ./scripts/docs.py new-lang ht

Successfully initialized: docs/ht

これで、コードエディタで新しく作成されたディレクトリdocs/ht/を確認できます。

そのコマンドは、enバージョンからすべてを継承するシンプルな設定のファイルdocs/ht/mkdocs.ymlを作成しました。

INHERIT: ../en/mkdocs.yml

ヒント

そのファイルをこれらの内容で手動で作成することもできます。

そのコマンドは、メインページ用のダミーファイルdocs/ht/index.mdも作成しました。まずこれを翻訳することから始められます。

そのプロセスについては、「既存の言語」の以前の指示に進むことができます。

これら2つのファイル、docs/ht/mkdocs.ymlとdocs/ht/index.mdを含む最初のプルリクエストを作成できます。🎉

結果をプレビューする

上記で既に述べたように、./scripts/docs.pyをliveコマンド（またはmkdocs serve）とともに使用して結果をプレビューできます。

完了したら、他のすべての言語を含め、オンラインでどのように表示されるかをすべてテストすることもできます。

そのためには、まずすべてのドキュメントをビルドします。

// Use the command "build-all", this will take a bit
$ python ./scripts/docs.py build-all

Building docs for: en
Building docs for: es
Successfully built docs for: es

これにより、各言語のすべての独立したMkDocsサイトがビルドされ、それらが結合されて、./site/に最終出力が生成されます。

次に、serveコマンドでそれを提供できます。

// Use the command "serve" after running "build-all"
$ python ./scripts/docs.py serve

Warning: this is a very simple server. For development, use mkdocs serve instead.
This is here only to preview a site with translations already built.
Make sure you run the build-all command first.
Serving at: http://127.0.0.1:8008

翻訳に特化したヒントとガイドライン

  • Markdownドキュメント（.md）のみを翻訳してください。./docs_srcにあるコード例は翻訳しないでください。

  • Markdownドキュメント内のコードブロックでは、コメント（# a comment）は翻訳しますが、それ以外の部分は変更しないでください。

  • 「``」（インラインコード）で囲まれたものは何も変更しないでください。

  • ///で始まる行では、|の後のテキスト部分のみを翻訳してください。それ以外の部分は変更しないでください。

  • たとえば、/// warningのような情報ボックスを/// warning | Achtungのように翻訳できます。ただし、///の直後の単語は変更しないでください。情報ボックスの色を決定します。

  • 画像、コードファイル、Markdownドキュメントへのリンクのパスは変更しないでください。

  • ただし、Markdownドキュメントが翻訳されると、見出しへのリンクの#hash-partsが変更される場合があります。可能であれば、これらのリンクを更新してください。

    • 正規表現#[^# ]を使用して、翻訳されたドキュメントでそのようなリンクを検索します。
    • すでに翻訳されているすべてのドキュメントでyour-translated-document.mdを検索します。たとえば、VS Codeには「編集」->「ファイル内で検索」オプションがあります。
    • ドキュメントを翻訳するときは、未翻訳のドキュメントの見出しにリンクしている#hash-partsを「事前に翻訳」しないでください。