開発 - 貢献¶

まず、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 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ディスカッションがあるかどうかを確認してください。それを購読すると、レビューすべき新しいプルリクエストがあるときに、自動的にコメントがディスカッションに追加されます。
ページを翻訳する場合は、翻訳されたページごとに単一のプルリクエストを追加してください。そうすることで、他の人がレビューするのがはるかに簡単になります。
翻訳したい言語の2文字コードを確認するには、ISO 639-1コードの一覧の表を使用できます。

既存の言語¶

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

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

ヒント

メイン（「公式」）言語は英語で、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/es/ にあります。

$ cd docs/es/

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

$ mkdocs serve --dev-addr 8008

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

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

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

次のファイルをコピーします。

docs/en/docs/features.md

まったく同じ場所に貼り付けますが、翻訳したい言語（たとえば）

docs/es/docs/features.md

ヒント

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

ブラウザにアクセスすると、ドキュメントに新しいセクションが表示されるようになったことがわかります（上部の情報ボックスは消えています）。🎉

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

翻訳しないページ¶

🚨 翻訳しないでください

reference/ の下のファイル
release-notes.md
fastapi-people.md
external-links.md
newsletter.md
management-tasks.md
management.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 を作成しました。それから翻訳を開始できます。

そのプロセスの「既存の言語」の前の手順を続けることができます。

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

結果のプレビュー¶

すでに上記で述べたように、./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ドキュメント内のコードブロックでは、コメント（# コメント）を翻訳しますが、残りは変更しません。
「``」（インラインコード）で囲まれたものは何も変更しないでください。
/// で始まる行では、"... テキスト ..." の部分のみを翻訳します。残りは変更しないでください。
/// warning のような情報ボックスは、たとえば /// warning | Achtung で翻訳できます。ただし、/// の直後の単語は変更しないでください。情報ボックスの色を決定します。
画像、コードファイル、Markdownドキュメントへのリンクのパスを変更しないでください。
ただし、Markdownドキュメントが翻訳されると、その見出しへのリンクの #ハッシュ部分 が変更される可能性があります。可能であれば、これらのリンクを更新してください。
- 翻訳されたドキュメントで、正規表現 #[^# ] を使用してこのようなリンクを検索します。
- あなたの言語に翻訳されたすべてのドキュメントで、your-translated-document.md を検索します。たとえば、VS Codeには「編集」->「ファイル内検索」オプションがあります。
- ドキュメントを翻訳するときは、翻訳されていないドキュメントの見出しにリンクする #ハッシュ部分 を「事前翻訳」しないでください。