mirror
/
tiangolo.fastapi
mirror of https://github.com/tiangolo/fastapi
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

📝 Update `contributing.md` docs, include note to not translate this page (#12841)

pull/12898/head
Sebastián Ramírez 5 months ago
committed by GitHub
parent
290e1060ca
commit
8767a31c80
No known key found for this signature in database GPG Key ID: B5690EEEBB952194
9 changed files with 3 additions and 3484 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 484
      docs/de/docs/contributing.md
  2. 493
      docs/em/docs/contributing.md
  3. 3
      docs/en/docs/contributing.md
  4. 533
      docs/fr/docs/contributing.md
  5. 498
      docs/ja/docs/contributing.md
  6. 507
      docs/pt/docs/contributing.md
  7. 496
      docs/ru/docs/contributing.md
  8. 472
      docs/zh/docs/contributing.md
  9. 1
      scripts/docs.py

484
docs/de/docs/contributing.md
View File

@ -1,484 +0,0 @@
# Entwicklung – Mitwirken
Vielleicht möchten Sie sich zuerst die grundlegenden Möglichkeiten anschauen, [FastAPI zu helfen und Hilfe zu erhalten](help-fastapi.md){.internal-link target=_blank}.
## Entwicklung
Wenn Sie das <a href="https://github.com/fastapi/fastapi" class="external-link" target="_blank">fastapi Repository</a> bereits geklont haben und tief in den Code eintauchen möchten, hier einen Leitfaden zum Einrichten Ihrer Umgebung.
### Virtuelle Umgebung mit `venv`
Sie können mit dem Python-Modul `venv` in einem Verzeichnis eine isolierte virtuelle lokale Umgebung erstellen. Machen wir das im geklonten Repository (da wo sich die `requirements.txt` befindet):
<div class="termy">
```console
$ python -m venv env
```
</div>
Das erstellt ein Verzeichnis `./env/` mit den Python-Binärdateien und Sie können dann Packages in dieser lokalen Umgebung installieren.
### Umgebung aktivieren
Aktivieren Sie die neue Umgebung mit:
//// tab | Linux, macOS
<div class="termy">
```console
$ source ./env/bin/activate
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
$ .\env\Scripts\Activate.ps1
```
</div>
////
//// tab | Windows Bash
Oder, wenn Sie Bash für Windows verwenden (z. B. <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>):
<div class="termy">
```console
$ source ./env/Scripts/activate
```
</div>
////
Um zu überprüfen, ob es funktioniert hat, geben Sie ein:
//// tab | Linux, macOS, Windows Bash
<div class="termy">
```console
$ which pip
some/directory/fastapi/env/bin/pip
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
$ Get-Command pip
some/directory/fastapi/env/bin/pip
```
</div>
////
Wenn die `pip` Binärdatei unter `env/bin/pip` angezeigt wird, hat es funktioniert. 🎉
Stellen Sie sicher, dass Sie über die neueste Version von pip in Ihrer lokalen Umgebung verfügen, um Fehler bei den nächsten Schritten zu vermeiden:
<div class="termy">
```console
$ python -m pip install --upgrade pip
---> 100%
```
</div>
/// tip | Tipp
Aktivieren Sie jedes Mal, wenn Sie ein neues Package mit `pip` in dieser Umgebung installieren, die Umgebung erneut.
Dadurch wird sichergestellt, dass Sie, wenn Sie ein von diesem Package installiertes Terminalprogramm verwenden, das Programm aus Ihrer lokalen Umgebung verwenden und kein anderes, das global installiert sein könnte.
///
### Benötigtes mit pip installieren
Nachdem Sie die Umgebung wie oben beschrieben aktiviert haben:
<div class="termy">
```console
$ pip install -r requirements.txt
---> 100%
```
</div>
Das installiert alle Abhängigkeiten und Ihr lokales FastAPI in Ihrer lokalen Umgebung.
#### Das lokale FastAPI verwenden
Wenn Sie eine Python-Datei erstellen, die FastAPI importiert und verwendet, und diese mit dem Python aus Ihrer lokalen Umgebung ausführen, wird Ihr geklonter lokaler FastAPI-Quellcode verwendet.
Und wenn Sie diesen lokalen FastAPI-Quellcode aktualisieren und dann die Python-Datei erneut ausführen, wird die neue Version von FastAPI verwendet, die Sie gerade bearbeitet haben.
Auf diese Weise müssen Sie Ihre lokale Version nicht „installieren“, um jede Änderung testen zu können.
/// note | Technische Details
Das geschieht nur, wenn Sie die Installation mit der enthaltenen `requirements.txt` durchführen, anstatt `pip install fastapi` direkt auszuführen.
Das liegt daran, dass in der Datei `requirements.txt` die lokale Version von FastAPI mit der Option `-e` für die Installation im „editierbaren“ Modus markiert ist.
///
### Den Code formatieren
Es gibt ein Skript, das, wenn Sie es ausführen, Ihren gesamten Code formatiert und bereinigt:
<div class="termy">
```console
$ bash scripts/format.sh
```
</div>
Es sortiert auch alle Ihre Importe automatisch.
Damit es sie richtig sortiert, muss FastAPI lokal in Ihrer Umgebung installiert sein, mit dem Befehl vom obigen Abschnitt, welcher `-e` verwendet.
## Dokumentation
Stellen Sie zunächst sicher, dass Sie Ihre Umgebung wie oben beschrieben einrichten, was alles Benötigte installiert.
### Dokumentation live
Während der lokalen Entwicklung gibt es ein Skript, das die Site erstellt, auf Änderungen prüft und direkt neu lädt (Live Reload):
<div class="termy">
```console
$ 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
```
</div>
Das stellt die Dokumentation unter `http://127.0.0.1:8008` bereit.
Auf diese Weise können Sie die Dokumentation/Quelldateien bearbeiten und die Änderungen live sehen.
/// tip | Tipp
Alternativ können Sie die Schritte des Skripts auch manuell ausführen.
Gehen Sie in das Verzeichnis für die entsprechende Sprache. Das für die englischsprachige Hauptdokumentation befindet sich unter `docs/en/`:
```console
$ cd docs/en/
```
Führen Sie dann `mkdocs` in diesem Verzeichnis aus:
```console
$ mkdocs serve --dev-addr 8008
```
///
#### Typer-CLI (optional)
Die Anleitung hier zeigt Ihnen, wie Sie das Skript unter `./scripts/docs.py` direkt mit dem `python` Programm verwenden.
Sie können aber auch <a href="https://typer.tiangolo.com/typer-cli/" class="external-link" target="_blank">Typer CLI</a> verwenden und erhalten dann Autovervollständigung für Kommandos in Ihrem Terminal, nach dem Sie dessen Vervollständigung installiert haben.
Wenn Sie Typer CLI installieren, können Sie die Vervollständigung installieren mit:
<div class="termy">
```console
$ typer --install-completion
zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.
```
</div>
### Dokumentationsstruktur
Die Dokumentation verwendet <a href="https://www.mkdocs.org/" class="external-link" target="_blank">MkDocs</a>.
Und es gibt zusätzliche Tools/Skripte für Übersetzungen, in `./scripts/docs.py`.
/// tip | Tipp
Sie müssen sich den Code in `./scripts/docs.py` nicht anschauen, verwenden Sie ihn einfach in der Kommandozeile.
///
Die gesamte Dokumentation befindet sich im Markdown-Format im Verzeichnis `./docs/en/`.
Viele der Tutorials enthalten Codeblöcke.
In den meisten Fällen handelt es sich bei diesen Codeblöcken um vollständige Anwendungen, die unverändert ausgeführt werden können.
Tatsächlich sind diese Codeblöcke nicht Teil des Markdowns, sondern Python-Dateien im Verzeichnis `./docs_src/`.
Und diese Python-Dateien werden beim Generieren der Site in die Dokumentation eingefügt.
### Dokumentation für Tests
Tatsächlich arbeiten die meisten Tests mit den Beispielquelldateien in der Dokumentation.
Dadurch wird sichergestellt, dass:
* Die Dokumentation aktuell ist.
* Die Dokumentationsbeispiele ohne Änderung ausgeführt werden können.
* Die meisten Funktionalitäten durch die Dokumentation abgedeckt werden, sichergestellt durch die Testabdeckung.
#### Gleichzeitig Apps und Dokumentation
Wenn Sie die Beispiele ausführen, mit z. B.:
<div class="termy">
```console
$ uvicorn tutorial001:app --reload
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
</div>
wird das, da Uvicorn standardmäßig den Port `8000` verwendet, mit der Dokumentation auf dem Port `8008` nicht in Konflikt geraten.
### Übersetzungen
Hilfe bei Übersetzungen wird SEHR geschätzt! Und es kann nicht getan werden, ohne die Hilfe der Gemeinschaft. 🌎 🚀
Hier sind die Schritte, die Ihnen bei Übersetzungen helfen.
#### Tipps und Richtlinien
* Schauen Sie nach <a href="https://github.com/fastapi/fastapi/pulls" class="external-link" target="_blank">aktuellen Pull Requests</a> für Ihre Sprache. Sie können die Pull Requests nach dem Label für Ihre Sprache filtern. Für Spanisch lautet das Label beispielsweise <a href="https://github.com/fastapi/fastapi/pulls?q=is%3Aopen+sort%3Aupdated-desc+label%3Alang-es+label%3Aawaiting-review" class="external-link" target="_blank">`lang-es`</a>.
* Sehen Sie diese Pull Requests durch (Review), schlagen Sie Änderungen vor, oder segnen Sie sie ab (Approval). Bei den Sprachen, die ich nicht spreche, warte ich, bis mehrere andere die Übersetzung durchgesehen haben, bevor ich den Pull Request merge.
/// tip | Tipp
Sie können <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request" class="external-link" target="_blank">Kommentare mit Änderungsvorschlägen</a> zu vorhandenen Pull Requests hinzufügen.
Schauen Sie sich die Dokumentation an, <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews" class="external-link" target="_blank">wie man ein Review zu einem Pull Request hinzufügt</a>, welches den PR absegnet oder Änderungen vorschlägt.
///
* Überprüfen Sie, ob es eine <a href="https://github.com/fastapi/fastapi/discussions/categories/translations" class="external-link" target="_blank">GitHub-Diskussion</a> gibt, die Übersetzungen für Ihre Sprache koordiniert. Sie können sie abonnieren, und wenn ein neuer Pull Request zum Review vorliegt, wird der Diskussion automatisch ein Kommentar hinzugefügt.
* Wenn Sie Seiten übersetzen, fügen Sie einen einzelnen Pull Request pro übersetzter Seite hinzu. Dadurch wird es für andere viel einfacher, ihn zu durchzusehen.
* Um den Zwei-Buchstaben-Code für die Sprache zu finden, die Sie übersetzen möchten, schauen Sie sich die Tabelle <a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes" class="external-link" target= verwenden "_blank">List of ISO 639-1 codes</a> an.
#### Vorhandene Sprache
Angenommen, Sie möchten eine Seite für eine Sprache übersetzen, die bereits Übersetzungen für einige Seiten hat, beispielsweise für Spanisch.
Im Spanischen lautet der Zwei-Buchstaben-Code `es`. Das Verzeichnis für spanische Übersetzungen befindet sich also unter `docs/es/`.
/// tip | Tipp
Die Haupt („offizielle“) Sprache ist Englisch und befindet sich unter `docs/en/`.
///
Führen Sie nun den Live-Server für die Dokumentation auf Spanisch aus:
<div class="termy">
```console
// Verwenden Sie das Kommando „live“ und fügen Sie den Sprach-Code als Argument hinten an
$ 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
```
</div>
/// tip | Tipp
Alternativ können Sie die Schritte des Skripts auch manuell ausführen.
Gehen Sie in das Sprachverzeichnis, für die spanischen Übersetzungen ist das `docs/es/`:
```console
$ cd docs/es/
```
Dann führen Sie in dem Verzeichnis `mkdocs` aus:
```console
$ mkdocs serve --dev-addr 8008
```
///
Jetzt können Sie auf <a href="http://127.0.0.1:8008" class="external-link" target="_blank">http://127.0.0.1:8008</a> gehen und Ihre Änderungen live sehen.
Sie werden sehen, dass jede Sprache alle Seiten hat. Einige Seiten sind jedoch nicht übersetzt und haben oben eine Info-Box, dass die Übersetzung noch fehlt.
Nehmen wir nun an, Sie möchten eine Übersetzung für den Abschnitt [Features](features.md){.internal-link target=_blank} hinzufügen.
* Kopieren Sie die Datei:
```
docs/en/docs/features.md
```
* Fügen Sie sie an genau derselben Stelle ein, jedoch für die Sprache, die Sie übersetzen möchten, z. B.:
```
docs/es/docs/features.md
```
/// tip | Tipp
Beachten Sie, dass die einzige Änderung in Pfad und Dateiname der Sprachcode ist, von `en` zu `es`.
///
Wenn Sie in Ihrem Browser nachsehen, werden Sie feststellen, dass die Dokumentation jetzt Ihren neuen Abschnitt anzeigt (die Info-Box oben ist verschwunden). 🎉
Jetzt können Sie alles übersetzen und beim Speichern sehen, wie es aussieht.
#### Neue Sprache
Nehmen wir an, Sie möchten Übersetzungen für eine Sprache hinzufügen, die noch nicht übersetzt ist, nicht einmal einige Seiten.
Angenommen, Sie möchten Übersetzungen für Kreolisch hinzufügen, diese sind jedoch noch nicht in den Dokumenten enthalten.
Wenn Sie den Link von oben überprüfen, lautet der Sprachcode für Kreolisch `ht`.
Der nächste Schritt besteht darin, das Skript auszuführen, um ein neues Übersetzungsverzeichnis zu erstellen:
<div class="termy">
```console
// Verwenden Sie das Kommando new-lang und fügen Sie den Sprach-Code als Argument hinten an
$ python ./scripts/docs.py new-lang ht
Successfully initialized: docs/ht
```
</div>
Jetzt können Sie in Ihrem Code-Editor das neu erstellte Verzeichnis `docs/ht/` sehen.
Obiges Kommando hat eine Datei `docs/ht/mkdocs.yml` mit einer Minimal-Konfiguration erstellt, die alles von der `en`-Version erbt:
```yaml
INHERIT: ../en/mkdocs.yml
```
/// tip | Tipp
Sie können diese Datei mit diesem Inhalt auch einfach manuell erstellen.
///
Das Kommando hat auch eine Dummy-Datei `docs/ht/index.md` für die Hauptseite erstellt. Sie können mit der Übersetzung dieser Datei beginnen.
Sie können nun mit den obigen Instruktionen für eine „vorhandene Sprache“ fortfahren.
Fügen Sie dem ersten Pull Request beide Dateien `docs/ht/mkdocs.yml` und `docs/ht/index.md` bei. 🎉
#### Vorschau des Ergebnisses
Wie bereits oben erwähnt, können Sie `./scripts/docs.py` mit dem Befehl `live` verwenden, um eine Vorschau der Ergebnisse anzuzeigen (oder `mkdocs serve`).
Sobald Sie fertig sind, können Sie auch alles so testen, wie es online aussehen würde, einschließlich aller anderen Sprachen.
Bauen Sie dazu zunächst die gesamte Dokumentation:
<div class="termy">
```console
// Verwenden Sie das Kommando „build-all“, das wird ein wenig dauern
$ python ./scripts/docs.py build-all
Building docs for: en
Building docs for: es
Successfully built docs for: es
```
</div>
Dadurch werden alle diese unabhängigen MkDocs-Sites für jede Sprache erstellt, kombiniert und das endgültige Resultat unter `./site/` gespeichert.
Dieses können Sie dann mit dem Befehl `serve` bereitstellen:
<div class="termy">
```console
// Verwenden Sie das Kommando „serve“ nachdem Sie „build-all“ ausgeführt haben.
$ 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
```
</div>
#### Übersetzungsspezifische Tipps und Richtlinien
* Übersetzen Sie nur die Markdown-Dokumente (`.md`). Übersetzen Sie nicht die Codebeispiele unter `./docs_src`.
* In Codeblöcken innerhalb des Markdown-Dokuments, übersetzen Sie Kommentare (`# ein Kommentar`), aber lassen Sie den Rest unverändert.
* Ändern Sie nichts, was in "``" (Inline-Code) eingeschlossen ist.
* In Zeilen, die mit `===` oder `!!!` beginnen, übersetzen Sie nur den ` "... Text ..."`-Teil. Lassen Sie den Rest unverändert.
* Sie können Info-Boxen wie `!!! warning` mit beispielsweise `!!! warning "Achtung"` übersetzen. Aber ändern Sie nicht das Wort direkt nach dem `!!!`, es bestimmt die Farbe der Info-Box.
* Ändern Sie nicht die Pfade in Links zu Bildern, Codedateien, Markdown Dokumenten.
* Wenn ein Markdown-Dokument übersetzt ist, ändern sich allerdings unter Umständen die `#hash-teile` in Links zu dessen Überschriften. Aktualisieren Sie diese Links, wenn möglich.
* Suchen Sie im übersetzten Dokument nach solchen Links mit dem Regex `#[^# ]`.
* Suchen Sie in allen bereits in ihre Sprache übersetzen Dokumenten nach `ihr-ubersetztes-dokument.md`. VS Code hat beispielsweise eine Option „Bearbeiten“ -> „In Dateien suchen“.
* Übersetzen Sie bei der Übersetzung eines Dokuments nicht „im Voraus“ `#hash-teile`, die zu Überschriften in noch nicht übersetzten Dokumenten verlinken.
## Tests
Es gibt ein Skript, das Sie lokal ausführen können, um den gesamten Code zu testen und Code Coverage Reporte in HTML zu generieren:
<div class="termy">
```console
$ bash scripts/test-cov-html.sh
```
</div>
Dieses Kommando generiert ein Verzeichnis `./htmlcov/`. Wenn Sie die Datei `./htmlcov/index.html` in Ihrem Browser öffnen, können Sie interaktiv die Codebereiche erkunden, die von den Tests abgedeckt werden, und feststellen, ob Bereiche fehlen.

493
docs/em/docs/contributing.md
View File

@ -1,493 +0,0 @@
# 🛠️ - 📉
🥇, 👆 💪 💚 👀 🔰 🌌 [ℹ FastAPI &amp; 🤚 ℹ](help-fastapi.md){.internal-link target=_blank}.
## 🛠️
🚥 👆 ⏪ 🖖 🗃 &amp; 👆 💭 👈 👆 💪 ⏬ 🤿 📟, 📥 📄 ⚒ 🆙 👆 🌐.
### 🕹 🌐 ⏮️ `venv`
👆 💪 ✍ 🕹 🌐 📁 ⚙️ 🐍 `venv` 🕹:
<div class="termy">
```console
$ python -m venv env
```
</div>
👈 🔜 ✍ 📁 `./env/` ⏮️ 🐍 💱 &amp; ⤴️ 👆 🔜 💪 ❎ 📦 👈 ❎ 🌐.
### 🔓 🌐
🔓 🆕 🌐 ⏮️:
//// tab | 💾, 🇸🇻
<div class="termy">
```console
$ source ./env/bin/activate
```
</div>
////
//// tab | 🚪 📋
<div class="termy">
```console
$ .\env\Scripts\Activate.ps1
```
</div>
////
//// tab | 🚪 🎉
⚖️ 🚥 👆 ⚙️ 🎉 🖥 (✅ <a href="https://gitforwindows.org/" class="external-link" target="_blank">🐛 🎉</a>):
<div class="termy">
```console
$ source ./env/Scripts/activate
```
</div>
////
✅ ⚫️ 👷, ⚙️:
//// tab | 💾, 🇸🇻, 🚪 🎉
<div class="termy">
```console
$ which pip
some/directory/fastapi/env/bin/pip
```
</div>
////
//// tab | 🚪 📋
<div class="termy">
```console
$ Get-Command pip
some/directory/fastapi/env/bin/pip
```
</div>
////
🚥 ⚫️ 🎦 `pip` 💱 `env/bin/pip` ⤴️ ⚫️ 👷. 👶
⚒ 💭 👆 ✔️ 📰 🐖 ⏬ 🔛 👆 🕹 🌐 ❎ ❌ 🔛 ⏭ 📶:
<div class="termy">
```console
$ python -m pip install --upgrade pip
---> 100%
```
</div>
/// tip
🔠 🕰 👆 ❎ 🆕 📦 ⏮️ `pip` 🔽 👈 🌐, 🔓 🌐 🔄.
👉 ⚒ 💭 👈 🚥 👆 ⚙️ 📶 📋 ❎ 👈 📦, 👆 ⚙️ 1️⃣ ⚪️➡️ 👆 🇧🇿 🌐 &amp; 🚫 🙆 🎏 👈 💪 ❎ 🌐.
///
### 🐖
⏮️ 🔓 🌐 🔬 🔛:
<div class="termy">
```console
$ pip install -r requirements.txt
---> 100%
```
</div>
⚫️ 🔜 ❎ 🌐 🔗 &amp; 👆 🇧🇿 FastAPI 👆 🇧🇿 🌐.
#### ⚙️ 👆 🇧🇿 FastAPI
🚥 👆 ✍ 🐍 📁 👈 🗄 &amp; ⚙️ FastAPI, &amp; 🏃 ⚫️ ⏮️ 🐍 ⚪️➡️ 👆 🇧🇿 🌐, ⚫️ 🔜 ⚙️ 👆 🇧🇿 FastAPI ℹ 📟.
&amp; 🚥 👆 ℹ 👈 🇧🇿 FastAPI ℹ 📟, ⚫️ ❎ ⏮️ `-e`, 🕐❔ 👆 🏃 👈 🐍 📁 🔄, ⚫️ 🔜 ⚙️ 🍋 ⏬ FastAPI 👆 ✍.
👈 🌌, 👆 🚫 ✔️ "❎" 👆 🇧🇿 ⏬ 💪 💯 🔠 🔀.
### 📁
📤 ✍ 👈 👆 💪 🏃 👈 🔜 📁 &amp; 🧹 🌐 👆 📟:
<div class="termy">
```console
$ bash scripts/format.sh
```
</div>
⚫️ 🔜 🚘-😇 🌐 👆 🗄.
⚫️ 😇 👫 ☑, 👆 💪 ✔️ FastAPI ❎ 🌐 👆 🌐, ⏮️ 📋 📄 🔛 ⚙️ `-e`.
## 🩺
🥇, ⚒ 💭 👆 ⚒ 🆙 👆 🌐 🔬 🔛, 👈 🔜 ❎ 🌐 📄.
🧾 ⚙️ <a href="https://www.mkdocs.org/" class="external-link" target="_blank">⬜</a>.
&amp; 📤 ➕ 🧰/✍ 🥉 🍵 ✍ `./scripts/docs.py`.
/// tip
👆 🚫 💪 👀 📟 `./scripts/docs.py`, 👆 ⚙️ ⚫️ 📋 ⏸.
///
🌐 🧾 ✍ 📁 📁 `./docs/en/`.
📚 🔰 ✔️ 🍫 📟.
🌅 💼, 👫 🍫 📟 ☑ 🏁 🈸 👈 💪 🏃.
👐, 👈 🍫 📟 🚫 ✍ 🔘 ✍, 👫 🐍 📁 `./docs_src/` 📁.
&amp; 👈 🐍 📁 🔌/💉 🧾 🕐❔ 🏭 🕸.
### 🩺 💯
🏆 💯 🤙 🏃 🛡 🖼 ℹ 📁 🧾.
👉 ℹ ⚒ 💭 👈:
* 🧾 🆙 📅.
* 🧾 🖼 💪 🏃.
* 🌅 ⚒ 📔 🧾, 🚚 💯 💰.
⏮️ 🇧🇿 🛠️, 📤 ✍ 👈 🏗 🕸 &amp; ✅ 🙆 🔀, 🖖-🔫:
<div class="termy">
```console
$ 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
```
</div>
⚫️ 🔜 🍦 🧾 🔛 `http://127.0.0.1:8008`.
👈 🌌, 👆 💪 ✍ 🧾/ℹ 📁 &amp; 👀 🔀 🖖.
#### 🏎 ✳ (📦)
👩‍🌾 📥 🎦 👆 ❔ ⚙️ ✍ `./scripts/docs.py` ⏮️ `python` 📋 🔗.
✋️ 👆 💪 ⚙️ <a href="https://typer.tiangolo.com/typer-cli/" class="external-link" target="_blank">🏎 ✳</a>, &amp; 👆 🔜 🤚 ✍ 👆 📶 📋 ⏮️ ❎ 🛠️.
🚥 👆 ❎ 🏎 ✳, 👆 💪 ❎ 🛠️ ⏮️:
<div class="termy">
```console
$ typer --install-completion
zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.
```
</div>
### 📱 &amp; 🩺 🎏 🕰
🚥 👆 🏃 🖼 ⏮️, ✅:
<div class="termy">
```console
$ uvicorn tutorial001:app --reload
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
</div>
Uvicorn 🔢 🔜 ⚙️ ⛴ `8000`, 🧾 🔛 ⛴ `8008` 🏆 🚫 ⚔.
### ✍
ℹ ⏮️ ✍ 📶 🌅 👍 ❗ &amp; ⚫️ 💪 🚫 🔨 🍵 ℹ ⚪️➡️ 👪. 👶 👶
📥 📶 ℹ ⏮️ ✍.
#### 💁‍♂ &amp; 📄
* ✅ ⏳ <a href="https://github.com/fastapi/fastapi/pulls" class="external-link" target="_blank">♻ 🚲 📨</a> 👆 🇪🇸 &amp; 🚮 📄 ✔ 🔀 ⚖️ ✔ 👫.
/// tip
👆 💪 <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request" class="external-link" target="_blank">🚮 🏤 ⏮️ 🔀 🔑</a> ♻ 🚲 📨.
✅ 🩺 🔃 <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews" class="external-link" target="_blank">❎ 🚲 📨 📄</a> ✔ ⚫️ ⚖️ 📨 🔀.
///
* ✅ <a href="https://github.com/fastapi/fastapi/issues" class="external-link" target="_blank">❔</a> 👀 🚥 📤 1️⃣ 🛠️ ✍ 👆 🇪🇸.
* 🚮 👁 🚲 📨 📍 📃 💬. 👈 🔜 ⚒ ⚫️ 🌅 ⏩ 🎏 📄 ⚫️.
🇪🇸 👤 🚫 💬, 👤 🔜 ⌛ 📚 🎏 📄 ✍ ⏭ 🔗.
* 👆 💪 ✅ 🚥 📤 ✍ 👆 🇪🇸 &amp; 🚮 📄 👫, 👈 🔜 ℹ 👤 💭 👈 ✍ ☑ &amp; 👤 💪 🔗 ⚫️.
* ⚙️ 🎏 🐍 🖼 &amp; 🕴 💬 ✍ 🩺. 👆 🚫 ✔️ 🔀 🕳 👉 👷.
* ⚙️ 🎏 🖼, 📁 📛, &amp; 🔗. 👆 🚫 ✔️ 🔀 🕳 ⚫️ 👷.
* ✅ 2️⃣-🔤 📟 🇪🇸 👆 💚 💬 👆 💪 ⚙️ 🏓 <a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes" class="external-link" target="_blank">📇 💾 6️⃣3️⃣9️⃣-1️⃣ 📟</a>.
#### ♻ 🇪🇸
➡️ 💬 👆 💚 💬 📃 🇪🇸 👈 ⏪ ✔️ ✍ 📃, 💖 🇪🇸.
💼 🇪🇸, 2️⃣-🔤 📟 `es`. , 📁 🇪🇸 ✍ 🔎 `docs/es/`.
/// tip
👑 ("🛂") 🇪🇸 🇪🇸, 🔎 `docs/en/`.
///
🔜 🏃 🖖 💽 🩺 🇪🇸:
<div class="termy">
```console
// 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
```
</div>
🔜 👆 💪 🚶 <a href="http://127.0.0.1:8008" class="external-link" target="_blank">http://127.0.0.1:8008</a> &amp; 👀 👆 🔀 🖖.
🚥 👆 👀 FastAPI 🩺 🕸, 👆 🔜 👀 👈 🔠 🇪🇸 ✔️ 🌐 📃. ✋️ 📃 🚫 💬 &amp; ✔️ 📨 🔃 ❌ ✍.
✋️ 🕐❔ 👆 🏃 ⚫️ 🌐 💖 👉, 👆 🔜 🕴 👀 📃 👈 ⏪ 💬.
🔜 ➡️ 💬 👈 👆 💚 🚮 ✍ 📄 [⚒](features.md){.internal-link target=_blank}.
* 📁 📁:
```
docs/en/docs/features.md
```
* 📋 ⚫️ ⚫️❔ 🎏 🗺 ✋️ 🇪🇸 👆 💚 💬, ✅:
```
docs/es/docs/features.md
```
/// tip
👀 👈 🕴 🔀 ➡ &amp; 📁 📛 🇪🇸 📟, ⚪️➡️ `en` `es`.
///
* 🔜 📂 ⬜ 📁 📁 🇪🇸:
```
docs/en/mkdocs.yml
```
* 🔎 🥉 🌐❔ 👈 `docs/features.md` 🔎 📁 📁. 👱 💖:
```YAML hl_lines="8"
site_name: FastAPI
# More stuff
nav:
- FastAPI: index.md
- Languages:
- en: /
- es: /es/
- features.md
```
* 📂 ⬜ 📁 📁 🇪🇸 👆 ✍, ✅:
```
docs/es/mkdocs.yml
```
* 🚮 ⚫️ 📤 ☑ 🎏 🗺 ⚫️ 🇪🇸, ✅:
```YAML hl_lines="8"
site_name: FastAPI
# More stuff
nav:
- FastAPI: index.md
- Languages:
- en: /
- es: /es/
- features.md
```
⚒ 💭 👈 🚥 📤 🎏 ⛔, 🆕 ⛔ ⏮️ 👆 ✍ ⚫️❔ 🎏 ✔ 🇪🇸 ⏬.
🚥 👆 🚶 👆 🖥 👆 🔜 👀 👈 🔜 🩺 🎦 👆 🆕 📄. 👶
🔜 👆 💪 💬 ⚫️ 🌐 &amp; 👀 ❔ ⚫️ 👀 👆 🖊 📁.
#### 🆕 🇪🇸
➡️ 💬 👈 👆 💚 🚮 ✍ 🇪🇸 👈 🚫 💬, 🚫 📃.
➡️ 💬 👆 💚 🚮 ✍ 🇭🇹, &amp; ⚫️ 🚫 📤 🩺.
✅ 🔗 ⚪️➡️ 🔛, 📟 "🇭🇹" `ht`.
⏭ 🔁 🏃 ✍ 🏗 🆕 ✍ 📁:
<div class="termy">
```console
// Use the command new-lang, pass the language code as a CLI argument
$ python ./scripts/docs.py new-lang ht
Successfully initialized: docs/ht
Updating ht
Updating en
```
</div>
🔜 👆 💪 ✅ 👆 📟 👨‍🎨 ⏳ ✍ 📁 `docs/ht/`.
/// tip
✍ 🥇 🚲 📨 ⏮️ 👉, ⚒ 🆙 📳 🆕 🇪🇸, ⏭ ❎ ✍.
👈 🌌 🎏 💪 ℹ ⏮️ 🎏 📃 ⏪ 👆 👷 🔛 🥇 🕐. 👶
///
▶️ ✍ 👑 📃, `docs/ht/index.md`.
⤴️ 👆 💪 😣 ⏮️ ⏮️ 👩‍🌾, "♻ 🇪🇸".
##### 🆕 🇪🇸 🚫 🐕‍🦺
🚥 🕐❔ 🏃‍♂ 🖖 💽 ✍ 👆 🤚 ❌ 🔃 🇪🇸 🚫 ➖ 🐕‍🦺, 🕳 💖:
```
raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: partials/language/xx.html
```
👈 ⛓ 👈 🎢 🚫 🐕‍🦺 👈 🇪🇸 (👉 💼, ⏮️ ❌ 2️⃣-🔤 📟 `xx`).
✋️ 🚫 😟, 👆 💪 ⚒ 🎢 🇪🇸 🇪🇸 &amp; ⤴️ 💬 🎚 🩺.
🚥 👆 💪 👈, ✍ `mkdocs.yml` 👆 🆕 🇪🇸, ⚫️ 🔜 ✔️ 🕳 💖:
```YAML hl_lines="5"
site_name: FastAPI
# More stuff
theme:
# More stuff
language: xx
```
🔀 👈 🇪🇸 ⚪️➡️ `xx` (⚪️➡️ 👆 🇪🇸 📟) `en`.
⤴️ 👆 💪 ▶️ 🖖 💽 🔄.
#### 🎮 🏁
🕐❔ 👆 ⚙️ ✍ `./scripts/docs.py` ⏮️ `live` 📋 ⚫️ 🕴 🎦 📁 &amp; ✍ 💪 ⏮️ 🇪🇸.
✋️ 🕐 👆 🔨, 👆 💪 💯 ⚫️ 🌐 ⚫️ 🔜 👀 💳.
👈, 🥇 🏗 🌐 🩺:
<div class="termy">
```console
// Use the command "build-all", this will take a bit
$ python ./scripts/docs.py build-all
Updating es
Updating en
Building docs for: en
Building docs for: es
Successfully built docs for: es
Copying en index.md to README.md
```
</div>
👈 🏗 🌐 🩺 `./docs_build/` 🔠 🇪🇸. 👉 🔌 ❎ 🙆 📁 ⏮️ ❌ ✍, ⏮️ 🗒 💬 👈 "👉 📁 🚫 ✔️ ✍". ✋️ 👆 🚫 ✔️ 🕳 ⏮️ 👈 📁.
⤴️ ⚫️ 🏗 🌐 👈 🔬 ⬜ 🕸 🔠 🇪🇸, 🌀 👫, &amp; 🏗 🏁 🔢 `./site/`.
⤴️ 👆 💪 🍦 👈 ⏮️ 📋 `serve`:
<div class="termy">
```console
// 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
```
</div>
## 💯
📤 ✍ 👈 👆 💪 🏃 🌐 💯 🌐 📟 &amp; 🏗 💰 📄 🕸:
<div class="termy">
```console
$ bash scripts/test-cov-html.sh
```
</div>
👉 📋 🏗 📁 `./htmlcov/`, 🚥 👆 📂 📁 `./htmlcov/index.html` 👆 🖥, 👆 💪 🔬 🖥 🇹🇼 📟 👈 📔 💯, &amp; 👀 🚥 📤 🙆 🇹🇼 ❌.

3
docs/en/docs/contributing.md
View File

@ -289,6 +289,7 @@ Now you can translate it all and see how it looks as you save the file.
* `newsletter.md`
* `management-tasks.md`
* `management.md`
* `contributing.md`
Some of these files are updated very frequently and a translation would always be behind, or they include the main content from English source files, etc.
@ -380,7 +381,7 @@ Serving at: http://127.0.0.1:8008
* Do not change anything enclosed in "``" (inline code).
* In lines starting with `///` translate only the ` "... Text ..."` part. Leave the rest unchanged.
* In lines starting with `///` translate only the text part after `|`. Leave the rest unchanged.
* You can translate info boxes like `/// warning` with for example `/// warning | Achtung`. But do not change the word immediately after the `///`, it determines the color of the info box.

533
docs/fr/docs/contributing.md
View File

@ -1,533 +0,0 @@
# Développement - Contribuer
Tout d'abord, vous voudrez peut-être voir les moyens de base pour [aider FastAPI et obtenir de l'aide](help-fastapi.md){.internal-link target=_blank}.
## Développement
Si vous avez déjà cloné le dépôt et que vous savez que vous devez vous plonger dans le code, voici quelques directives pour mettre en place votre environnement.
### Environnement virtuel avec `venv`
Vous pouvez créer un environnement virtuel dans un répertoire en utilisant le module `venv` de Python :
<div class="termy">
```console
$ python -m venv env
```
</div>
Cela va créer un répertoire `./env/` avec les binaires Python et vous pourrez alors installer des paquets pour cet environnement isolé.
### Activer l'environnement
Activez le nouvel environnement avec :
//// tab | Linux, macOS
<div class="termy">
```console
$ source ./env/bin/activate
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
$ .\env\Scripts\Activate.ps1
```
</div>
////
//// tab | Windows Bash
Ou si vous utilisez Bash pour Windows (par exemple <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>):
<div class="termy">
```console
$ source ./env/Scripts/activate
```
</div>
////
Pour vérifier que cela a fonctionné, utilisez :
//// tab | Linux, macOS, Windows Bash
<div class="termy">
```console
$ which pip
some/directory/fastapi/env/bin/pip
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
$ Get-Command pip
some/directory/fastapi/env/bin/pip
```
</div>
////
Si celui-ci montre le binaire `pip` à `env/bin/pip`, alors ça a fonctionné. 🎉
/// tip
Chaque fois que vous installez un nouveau paquet avec `pip` sous cet environnement, activez à nouveau l'environnement.
Cela permet de s'assurer que si vous utilisez un programme terminal installé par ce paquet (comme `flit`), vous utilisez celui de votre environnement local et pas un autre qui pourrait être installé globalement.
///
### Flit
**FastAPI** utilise <a href="https://flit.readthedocs.io/en/latest/index.html" class="external-link" target="_blank">Flit</a> pour build, packager et publier le projet.
Après avoir activé l'environnement comme décrit ci-dessus, installez `flit` :
<div class="termy">
```console
$ pip install flit
---> 100%
```
</div>
Réactivez maintenant l'environnement pour vous assurer que vous utilisez le "flit" que vous venez d'installer (et non un environnement global).
Et maintenant, utilisez `flit` pour installer les dépendances de développement :
//// tab | Linux, macOS
<div class="termy">
```console
$ flit install --deps develop --symlink
---> 100%
```
</div>
////
//// tab | Windows
Si vous êtes sous Windows, utilisez `--pth-file` au lieu de `--symlink` :
<div class="termy">
```console
$ flit install --deps develop --pth-file
---> 100%
```
</div>
////
Il installera toutes les dépendances et votre FastAPI local dans votre environnement local.
#### Utiliser votre FastAPI local
Si vous créez un fichier Python qui importe et utilise FastAPI, et que vous l'exécutez avec le Python de votre environnement local, il utilisera votre code source FastAPI local.
Et si vous mettez à jour le code source local de FastAPI, tel qu'il est installé avec `--symlink` (ou `--pth-file` sous Windows), lorsque vous exécutez à nouveau ce fichier Python, il utilisera la nouvelle version de FastAPI que vous venez d'éditer.
De cette façon, vous n'avez pas à "installer" votre version locale pour pouvoir tester chaque changement.
### Formatage
Il existe un script que vous pouvez exécuter qui formatera et nettoiera tout votre code :
<div class="termy">
```console
$ bash scripts/format.sh
```
</div>
Il effectuera également un tri automatique de touts vos imports.
Pour qu'il puisse les trier correctement, vous devez avoir FastAPI installé localement dans votre environnement, avec la commande dans la section ci-dessus en utilisant `--symlink` (ou `--pth-file` sous Windows).
### Formatage des imports
Il existe un autre script qui permet de formater touts les imports et de s'assurer que vous n'avez pas d'imports inutilisés :
<div class="termy">
```console
$ bash scripts/format-imports.sh
```
</div>
Comme il exécute une commande après l'autre et modifie et inverse de nombreux fichiers, il prend un peu plus de temps à s'exécuter, il pourrait donc être plus facile d'utiliser fréquemment `scripts/format.sh` et `scripts/format-imports.sh` seulement avant de commit.
## Documentation
Tout d'abord, assurez-vous que vous configurez votre environnement comme décrit ci-dessus, qui installera toutes les exigences.
La documentation utilise <a href="https://www.mkdocs.org/" class="external-link" target="_blank">MkDocs</a>.
Et il y a des outils/scripts supplémentaires en place pour gérer les traductions dans `./scripts/docs.py`.
/// tip
Vous n'avez pas besoin de voir le code dans `./scripts/docs.py`, vous l'utilisez simplement dans la ligne de commande.
///
Toute la documentation est au format Markdown dans le répertoire `./docs/fr/`.
De nombreux tutoriels comportent des blocs de code.
Dans la plupart des cas, ces blocs de code sont de véritables applications complètes qui peuvent être exécutées telles quelles.
En fait, ces blocs de code ne sont pas écrits à l'intérieur du Markdown, ce sont des fichiers Python dans le répertoire `./docs_src/`.
Et ces fichiers Python sont inclus/injectés dans la documentation lors de la génération du site.
### Documentation pour les tests
La plupart des tests sont en fait effectués par rapport aux exemples de fichiers sources dans la documentation.
Cela permet de s'assurer que :
* La documentation est à jour.
* Les exemples de documentation peuvent être exécutés tels quels.
* La plupart des fonctionnalités sont couvertes par la documentation, assurées par la couverture des tests.
Au cours du développement local, un script build le site et vérifie les changements éventuels, puis il est rechargé en direct :
<div class="termy">
```console
$ 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
```
</div>
Il servira la documentation sur `http://127.0.0.1:8008`.
De cette façon, vous pouvez modifier la documentation/les fichiers sources et voir les changements en direct.
#### Typer CLI (facultatif)
Les instructions ici vous montrent comment utiliser le script à `./scripts/docs.py` avec le programme `python` directement.
Mais vous pouvez également utiliser <a href="https://typer.tiangolo.com/typer-cli/" class="external-link" target="_blank">Typer CLI</a>, et vous obtiendrez l'auto-complétion dans votre terminal pour les commandes après l'achèvement de l'installation.
Si vous installez Typer CLI, vous pouvez installer la complétion avec :
<div class="termy">
```console
$ typer --install-completion
zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.
```
</div>
### Apps et documentation en même temps
Si vous exécutez les exemples avec, par exemple :
<div class="termy">
```console
$ uvicorn tutorial001:app --reload
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
</div>
Comme Uvicorn utilisera par défaut le port `8000`, la documentation sur le port `8008` n'entrera pas en conflit.
### Traductions
L'aide aux traductions est TRÈS appréciée ! Et cela ne peut se faire sans l'aide de la communauté. 🌎 🚀
Voici les étapes à suivre pour aider à la traduction.
#### Conseils et lignes directrices
* Vérifiez les <a href="https://github.com/fastapi/fastapi/pulls" class="external-link" target="_blank">pull requests existantes</a> pour votre langue et ajouter des reviews demandant des changements ou les approuvant.
/// tip
Vous pouvez <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request" class="external-link" target="_blank">ajouter des commentaires avec des suggestions de changement</a> aux pull requests existantes.
Consultez les documents concernant <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews" class="external-link" target="_blank">l'ajout d'un review de pull request</a> pour l'approuver ou demander des modifications.
///
* Vérifiez dans <a href="https://github.com/fastapi/fastapi/issues" class="external-link" target="_blank">issues</a> pour voir s'il y a une personne qui coordonne les traductions pour votre langue.
* Ajoutez une seule pull request par page traduite. Il sera ainsi beaucoup plus facile pour les autres de l'examiner.
Pour les langues que je ne parle pas, je vais attendre plusieurs autres reviews de la traduction avant de merge.
* Vous pouvez également vérifier s'il existe des traductions pour votre langue et y ajouter une review, ce qui m'aidera à savoir si la traduction est correcte et je pourrai la fusionner.
* Utilisez les mêmes exemples en Python et ne traduisez que le texte des documents. Vous n'avez pas besoin de changer quoi que ce soit pour que cela fonctionne.
* Utilisez les mêmes images, noms de fichiers et liens. Vous n'avez pas besoin de changer quoi que ce soit pour que cela fonctionne.
* Pour vérifier le code à 2 lettres de la langue que vous souhaitez traduire, vous pouvez utiliser le tableau <a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes" class="external-link" target="_blank">Liste des codes ISO 639-1</a>.
#### Langue existante
Disons que vous voulez traduire une page pour une langue qui a déjà des traductions pour certaines pages, comme l'espagnol.
Dans le cas de l'espagnol, le code à deux lettres est `es`. Ainsi, le répertoire des traductions espagnoles se trouve à l'adresse `docs/es/`.
/// tip
La langue principale ("officielle") est l'anglais, qui se trouve à l'adresse "docs/en/".
///
Maintenant, lancez le serveur en live pour les documents en espagnol :
<div class="termy">
```console
// 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
```
</div>
Vous pouvez maintenant aller sur <a href="http://127.0.0.1:8008" class="external-link" target="_blank">http://127.0.0.1:8008</a> et voir vos changements en direct.
Si vous regardez le site web FastAPI docs, vous verrez que chaque langue a toutes les pages. Mais certaines pages ne sont pas traduites et sont accompagnées d'une notification concernant la traduction manquante.
Mais si vous le gérez localement de cette manière, vous ne verrez que les pages déjà traduites.
Disons maintenant que vous voulez ajouter une traduction pour la section [Features](features.md){.internal-link target=_blank}.
* Copiez le fichier à :
```
docs/en/docs/features.md
```
* Collez-le exactement au même endroit mais pour la langue que vous voulez traduire, par exemple :
```
docs/es/docs/features.md
```
/// tip
Notez que le seul changement dans le chemin et le nom du fichier est le code de langue, qui passe de `en` à `es`.
///
* Ouvrez maintenant le fichier de configuration de MkDocs pour l'anglais à
```
docs/en/docs/mkdocs.yml
```
* Trouvez l'endroit où cette `docs/features.md` se trouve dans le fichier de configuration. Quelque part comme :
```YAML hl_lines="8"
site_name: FastAPI
# More stuff
nav:
- FastAPI: index.md
- Languages:
- en: /
- es: /es/
- features.md
```
* Ouvrez le fichier de configuration MkDocs pour la langue que vous éditez, par exemple :
```
docs/es/docs/mkdocs.yml
```
* Ajoutez-le à l'endroit exact où il se trouvait pour l'anglais, par exemple :
```YAML hl_lines="8"
site_name: FastAPI
# More stuff
nav:
- FastAPI: index.md
- Languages:
- en: /
- es: /es/
- features.md
```
Assurez-vous que s'il y a d'autres entrées, la nouvelle entrée avec votre traduction est exactement dans le même ordre que dans la version anglaise.
Si vous allez sur votre navigateur, vous verrez que maintenant les documents montrent votre nouvelle section. 🎉
Vous pouvez maintenant tout traduire et voir à quoi cela ressemble au fur et à mesure que vous enregistrez le fichier.
#### Nouvelle langue
Disons que vous voulez ajouter des traductions pour une langue qui n'est pas encore traduite, pas même quelques pages.
Disons que vous voulez ajouter des traductions pour le Créole, et que ce n'est pas encore dans les documents.
En vérifiant le lien ci-dessus, le code pour "Créole" est `ht`.
L'étape suivante consiste à exécuter le script pour générer un nouveau répertoire de traduction :
<div class="termy">
```console
// Use the command new-lang, pass the language code as a CLI argument
$ python ./scripts/docs.py new-lang ht
Successfully initialized: docs/ht
Updating ht
Updating en
```
</div>
Vous pouvez maintenant vérifier dans votre éditeur de code le répertoire nouvellement créé `docs/ht/`.
/// tip
Créez une première demande d'extraction à l'aide de cette fonction, afin de configurer la nouvelle langue avant d'ajouter des traductions.
Ainsi, d'autres personnes peuvent vous aider à rédiger d'autres pages pendant que vous travaillez sur la première. 🚀
///
Commencez par traduire la page principale, `docs/ht/index.md`.
Vous pouvez ensuite continuer avec les instructions précédentes, pour une "langue existante".
##### Nouvelle langue non prise en charge
Si, lors de l'exécution du script du serveur en direct, vous obtenez une erreur indiquant que la langue n'est pas prise en charge, quelque chose comme :
```
raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: partials/language/xx.html
```
Cela signifie que le thème ne supporte pas cette langue (dans ce cas, avec un faux code de 2 lettres de `xx`).
Mais ne vous inquiétez pas, vous pouvez définir la langue du thème en anglais et ensuite traduire le contenu des documents.
Si vous avez besoin de faire cela, modifiez le fichier `mkdocs.yml` pour votre nouvelle langue, il aura quelque chose comme :
```YAML hl_lines="5"
site_name: FastAPI
# More stuff
theme:
# More stuff
language: xx
```
Changez cette langue de `xx` (de votre code de langue) à `fr`.
Vous pouvez ensuite relancer le serveur live.
#### Prévisualisez le résultat
Lorsque vous utilisez le script à `./scripts/docs.py` avec la commande `live`, il n'affiche que les fichiers et les traductions disponibles pour la langue courante.
Mais une fois que vous avez terminé, vous pouvez tester le tout comme il le ferait en ligne.
Pour ce faire, il faut d'abord construire tous les documents :
<div class="termy">
```console
// Use the command "build-all", this will take a bit
$ python ./scripts/docs.py build-all
Updating es
Updating en
Building docs for: en
Building docs for: es
Successfully built docs for: es
Copying en index.md to README.md
```
</div>
Cela génère tous les documents à `./docs_build/` pour chaque langue. Cela inclut l'ajout de tout fichier dont la traduction est manquante, avec une note disant que "ce fichier n'a pas encore de traduction". Mais vous n'avez rien à faire avec ce répertoire.
Ensuite, il construit tous ces sites MkDocs indépendants pour chaque langue, les combine, et génère le résultat final à `./site/`.
Ensuite, vous pouvez servir cela avec le commandement `serve`:
<div class="termy">
```console
// 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
```
</div>
## Tests
Il existe un script que vous pouvez exécuter localement pour tester tout le code et générer des rapports de couverture en HTML :
<div class="termy">
```console
$ bash scripts/test-cov-html.sh
```
</div>
Cette commande génère un répertoire `./htmlcov/`, si vous ouvrez le fichier `./htmlcov/index.html` dans votre navigateur, vous pouvez explorer interactivement les régions de code qui sont couvertes par les tests, et remarquer s'il y a une région manquante.

498
docs/ja/docs/contributing.md
View File

@ -1,498 +0,0 @@
# 開発 - 貢献
まず、[FastAPIを応援 - ヘルプの入手](help-fastapi.md){.internal-link target=_blank}の基本的な方法を見て、ヘルプを得た方がいいかもしれません。
## 開発
すでにリポジトリをクローンし、コードを詳しく調べる必要があるとわかっている場合に、環境構築のためのガイドラインをいくつか紹介します。
### `venv`を使用した仮想環境
Pythonの`venv`モジュールを使用して、ディレクトリに仮想環境を作成します:
<div class="termy">
```console
$ python -m venv env
```
</div>
これにより、Pythonバイナリを含む`./env/`ディレクトリが作成され、その隔離された環境にパッケージのインストールが可能になります。
### 仮想環境の有効化
新しい環境を有効化するには:
//// tab | Linux, macOS
<div class="termy">
```console
$ source ./env/bin/activate
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
$ .\env\Scripts\Activate.ps1
```
</div>
////
//// tab | Windows Bash
もしwindows用のBash (例えば、<a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>)を使っているなら:
<div class="termy">
```console
$ source ./env/Scripts/activate
```
</div>
////
動作の確認には、下記を実行します:
//// tab | Linux, macOS, Windows Bash
<div class="termy">
```console
$ which pip
some/directory/fastapi/env/bin/pip
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
$ Get-Command pip
some/directory/fastapi/env/bin/pip
```
</div>
////
`env/bin/pip`に`pip`バイナリが表示される場合は、正常に機能しています。🎉
/// tip | 豆知識
この環境で`pip`を使って新しいパッケージをインストールするたびに、仮想環境を再度有効化します。
これにより、そのパッケージによってインストールされたターミナルのプログラム を使用する場合、ローカル環境のものを使用し、グローバルにインストールされたものは使用されなくなります。
///
### pip
上記のように環境を有効化した後:
<div class="termy">
```console
$ pip install -r requirements.txt
---> 100%
```
</div>
これで、すべての依存関係とFastAPIを、ローカル環境にインストールします。
#### ローカル環境でFastAPIを使う
FastAPIをインポートして使用するPythonファイルを作成し、ローカル環境で実行すると、ローカルのFastAPIソースコードが使用されます。
そして、`-e` でインストールされているローカルのFastAPIソースコードを更新した場合、そのPythonファイルを再度実行すると、更新したばかりの新しいバージョンのFastAPIが使用されます。
これにより、ローカルバージョンを「インストール」しなくても、すべての変更をテストできます。
### コードの整形
すべてのコードを整形してクリーンにするスクリプトがあります:
<div class="termy">
```console
$ bash scripts/format.sh
```
</div>
また、すべてのインポートを自動でソートします。
正しく並べ替えるには、上記セクションのコマンドで `-e` を使い、FastAPIをローカル環境にインストールしている必要があります。
### インポートの整形
他にも、すべてのインポートを整形し、未使用のインポートがないことを確認するスクリプトがあります:
<div class="termy">
```console
$ bash scripts/format-imports.sh
```
</div>
多くのファイルを編集したり、リバートした後、これらのコマンドを実行すると、少し時間がかかります。なので`scripts/format.sh`を頻繁に使用し、`scripts/format-imports.sh`をコミット前に実行する方が楽でしょう。
## ドキュメント
まず、上記のように環境をセットアップしてください。すべての必要なパッケージがインストールされます。
ドキュメントは、<a href="https://www.mkdocs.org/" class="external-link" target="_blank">MkDocs</a>を使っています。
そして、翻訳を処理するためのツール/スクリプトが、`./scripts/docs.py`に用意されています。
/// tip | 豆知識
`./scripts/docs.py`のコードを見る必要はなく、コマンドラインからただ使うだけです。
///
すべてのドキュメントが、Markdown形式で`./docs/en/`ディレクトリにあります。
多くのチュートリアルには、コードブロックがあります。
ほとんどの場合、これらのコードブロックは、実際にそのまま実行できる完全なアプリケーションです。
実際、これらのコードブロックはMarkdown内には記述されておらず、`./docs_src/`ディレクトリのPythonファイルです。
そして、これらのPythonファイルは、サイトの生成時にドキュメントに含まれるか/挿入されます。
### ドキュメントのテスト
ほとんどのテストは、実際にドキュメント内のサンプルソースファイルに対して実行されます。
これにより、次のことが確認できます:
* ドキュメントが最新であること。
* ドキュメントの例が、そのまま実行できること。
* ほとんどの機能がドキュメントでカバーされており、テスト範囲で保証されていること。
ローカル開発中に、サイトを構築して変更がないかチェックするスクリプトがあり、ライブリロードされます:
<div class="termy">
```console
$ 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
```
</div>
ドキュメントは、`http://127.0.0.1:8008`で提供します。
そうすることで、ドキュメント/ソースファイルを編集し、変更をライブで見ることができます。
#### Typer CLI (任意)
ここでは、`./scripts/docs.py`のスクリプトを`python`プログラムで直接使う方法を説明します。
ですが<a href="https://typer.tiangolo.com/typer-cli/" class="external-link" target="_blank">Typer CLI</a>を使用して、インストール完了後にターミナルでの自動補完もできます。
Typer CLIをインストールする場合、次のコマンドで補完をインストールできます:
<div class="termy">
```console
$ typer --install-completion
zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.
```
</div>
### アプリとドキュメントを同時に
以下の様にサンプルを実行すると:
<div class="termy">
```console
$ uvicorn tutorial001:app --reload
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
</div>
Uvicornはデフォルトでポート`8000`を使用するため、ポート`8008`のドキュメントは衝突しません。
### 翻訳
翻訳のヘルプをとても歓迎しています！これはコミュニティの助けなしでは成し遂げられません。 🌎🚀
翻訳を支援するための手順は次のとおりです。
#### 豆知識とガイドライン
* あなたの言語の<a href="https://github.com/fastapi/fastapi/pulls" class="external-link" target="_blank">今あるプルリクエスト</a>を確認し、変更や承認をするレビューを追加します。
/// tip | 豆知識
すでにあるプルリクエストに<a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request" class="external-link" target="_blank">修正提案つきのコメントを追加</a>できます。
修正提案の承認のために<a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews" class="external-link" target="_blank">プルリクエストのレビューの追加</a>のドキュメントを確認してください。
///
* <a href="https://github.com/fastapi/fastapi/issues" class="external-link" target="_blank">issues</a>をチェックして、あなたの言語に対応する翻訳があるかどうかを確認してください。
* 翻訳したページごとに1つのプルリクエストを追加します。これにより、他のユーザーがレビューしやすくなります。
私が話さない言語については、他の何人かが翻訳をレビューするのを待って、マージします。
* 自分の言語の翻訳があるかどうか確認し、レビューを追加できます。これにより、翻訳が正しく、マージできることがわかります。
* 同じPythonの例を使用し、ドキュメント内のテキストのみを翻訳してください。何も変更する必要はありません。
* 同じ画像、ファイル名、リンクを使用します。何も変更する必要はありません。
* 翻訳する言語の2文字のコードを確認するには、表<a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes" class="external-link" target="_blank"> ISO 639-1コードのリスト</a>が使用できます。
#### すでにある言語
スペイン語の様に、既に一部のページが翻訳されている言語の翻訳を追加したいとしましょう。
スペイン語の場合、2文字のコードは`es`です。したがって、スペイン語のディレクトリは`docs/es/`です。
/// tip | 豆知識
メイン (「公式」) 言語は英語で、`docs/en/`にあります。
///
次に、ドキュメントのライブサーバーをスペイン語で実行します:
<div class="termy">
```console
// コマンド"live"を使用し、言語コードをCLIに引数で渡します。
$ 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
```
</div>
これで<a href="http://127.0.0.1:8008" class="external-link" target="_blank">http://127.0.0.1:8008</a> を開いて、変更を確認できます。
FastAPI docs Webサイトを見ると、すべての言語にすべてのページがあります。しかし、一部のページは翻訳されておらず、翻訳の欠落ページについて通知があります。
しかし、このようにローカルで実行すると、翻訳済みのページのみが表示されます。
ここで、セクション[Features](features.md){.internal-link target=_blank}の翻訳を追加するとします。
* 下記のファイルをコピーします:
```
docs/en/docs/features.md
```
* 翻訳したい言語のまったく同じところに貼り付けます。例えば:
```
docs/es/docs/features.md
```
/// tip | 豆知識
パスとファイル名の変更は、`en`から`es`への言語コードだけであることに注意してください。
///
* ここで、英語のMkDocs構成ファイルを開きます:
```
docs/en/docs/mkdocs.yml
```
* 設定ファイルの中で、`docs/features.md`が記述されている箇所を見つけます:
```YAML hl_lines="8"
site_name: FastAPI
# More stuff
nav:
- FastAPI: index.md
- Languages:
- en: /
- es: /es/
- features.md
```
* 編集している言語のMkDocs構成ファイルを開きます。例えば:
```
docs/es/docs/mkdocs.yml
```
* 英語とまったく同じ場所に追加します。例えば:
```YAML hl_lines="8"
site_name: FastAPI
# More stuff
nav:
- FastAPI: index.md
- Languages:
- en: /
- es: /es/
- features.md
```
他のエントリがある場合は、翻訳を含む新しいエントリが英語版とまったく同じ順序になっていることを確認してください。
ブラウザにアクセスすれば、ドキュメントに新しいセクションが表示されています。 🎉
これですべて翻訳して、ファイルを保存した状態を確認できます。
#### 新しい言語
まだ翻訳されていない言語の翻訳を追加したいとしましょう。
クレオール語の翻訳を追加したいのですが、それはまだドキュメントにありません。
上記のリンクを確認すると、「クレオール語」のコードは`ht`です。
次のステップは、スクリプトを実行して新しい翻訳ディレクトリを生成することです:
<div class="termy">
```console
// コマンド「new-lang」を使用して、言語コードをCLIに引数で渡します
$ python ./scripts/docs.py new-lang ht
Successfully initialized: docs/ht
Updating ht
Updating en
```
</div>
これで、新しく作成された`docs/ht/`ディレクトリをコードエディターから確認できます。
/// tip | 豆知識
翻訳を追加する前に、これだけで最初のプルリクエストを作成し、新しい言語の設定をセットアップします。
そうすることで、最初のページで作業している間、誰かの他のページの作業を助けることができます。 🚀
///
まず、メインページの`docs/ht/index.md`を翻訳します。
その後、「既存の言語」で、さきほどの手順を続行してください。
##### まだサポートされていない新しい言語
ライブサーバースクリプトを実行するときに、サポートされていない言語に関するエラーが発生した場合は、次のように表示されます:
```
raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: partials/language/xx.html
```
これは、テーマがその言語をサポートしていないことを意味します (この場合は、`xx`の2文字の偽のコード) 。
ただし、心配しないでください。テーマ言語を英語に設定して、ドキュメントの内容を翻訳できます。
その必要がある場合は、新しい言語の`mkdocs.yml`を次のように編集してください:
```YAML hl_lines="5"
site_name: FastAPI
# More stuff
theme:
# More stuff
language: xx
```
その言語を`xx` (あなたの言語コード) から`en`に変更します。
その後、ライブサーバーを再起動します。
#### 結果のプレビュー
`./scripts/docs.py`のスクリプトを`live`コマンドで使用すると、現在の言語で利用可能なファイルと翻訳のみが表示されます。
しかし一度実行したら、オンラインで表示されるのと同じように、すべてをテストできます。
このために、まずすべてのドキュメントをビルドします:
<div class="termy">
```console
// 「build-all」コマンドは少し時間がかかります。
$ python ./scripts/docs.py build-all
Updating es
Updating en
Building docs for: en
Building docs for: es
Successfully built docs for: es
Copying en index.md to README.md
```
</div>
これで、言語ごとにすべてのドキュメントが`./docs_build/`に作成されます。
これには、翻訳が欠落しているファイルを追加することと、「このファイルにはまだ翻訳がない」というメモが含まれます。ただし、そのディレクトリで何もする必要はありません。
次に、言語ごとにこれらすべての個別のMkDocsサイトを構築し、それらを組み合わせて、`./site/`に最終結果を出力します。
これは、コマンド`serve`で提供できます:
<div class="termy">
```console
// 「build-all」コマンドの実行の後に、「serve」コマンドを使います
$ 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
```
</div>
## テスト
すべてのコードをテストし、HTMLでカバレッジレポートを生成するためにローカルで実行できるスクリプトがあります:
<div class="termy">
```console
$ bash scripts/test-cov-html.sh
```
</div>
このコマンドは`./htmlcov/`ディレクトリを生成します。ブラウザでファイル`./htmlcov/index.html`を開くと、テストでカバーされているコードの領域をインタラクティブに探索できます。それによりテストが不足しているかどうか気付くことができます。

507
docs/pt/docs/contributing.md
View File

@ -1,507 +0,0 @@
# Desenvolvimento - Contribuindo
Primeiramente, você deveria ver os meios básicos para [ajudar FastAPI e pedir ajuda](help-fastapi.md){.internal-link target=_blank}.
## Desenvolvendo
Se você já clonou o repositório e precisa mergulhar no código, aqui estão algumas orientações para configurar seu ambiente.
### Ambiente virtual com `venv`
Você pode criar um ambiente virtual em um diretório utilizando o módulo `venv` do Python:
<div class="termy">
```console
$ python -m venv env
```
</div>
Isso criará o diretório `./env/` com os binários Python e então você será capaz de instalar pacotes nesse ambiente isolado.
### Ativar o ambiente
Ative o novo ambiente com:
//// tab | Linux, macOS
<div class="termy">
```console
$ source ./env/bin/activate
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
$ .\env\Scripts\Activate.ps1
```
</div>
////
//// tab | Windows Bash
Ou se você usa Bash para Windows (por exemplo <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>):
<div class="termy">
```console
$ source ./env/Scripts/activate
```
</div>
////
Para verificar se funcionou, use:
//// tab | Linux, macOS, Windows Bash
<div class="termy">
```console
$ which pip
some/directory/fastapi/env/bin/pip
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
$ Get-Command pip
some/directory/fastapi/env/bin/pip
```
</div>
////
Se ele exibir o binário `pip` em `env/bin/pip` então funcionou. 🎉
/// tip
Toda vez que você instalar um novo pacote com `pip` nesse ambiente, ative o ambiente novamente.
Isso garante que se você usar um programa instalado por aquele pacote, você utilizará aquele de seu ambiente local e não outro que possa estar instalado globalmente.
///
### pip
Após ativar o ambiente como descrito acima:
<div class="termy">
```console
$ pip install -r requirements.txt
---> 100%
```
</div>
Isso irá instalar todas as dependências e seu FastAPI local em seu ambiente local.
#### Usando seu FastAPI local
Se você cria um arquivo Python que importa e usa FastAPI, e roda com Python de seu ambiente local, ele irá utilizar o código fonte de seu FastAPI local.
E se você atualizar o código fonte do FastAPI local, como ele é instalado com `-e`, quando você rodar aquele arquivo Python novamente, ele irá utilizar a nova versão do FastAPI que você acabou de editar.
Desse modo, você não tem que "instalar" sua versão local para ser capaz de testar cada mudança.
### Formato
Tem um arquivo que você pode rodar que irá formatar e limpar todo o seu código:
<div class="termy">
```console
$ bash scripts/format.sh
```
</div>
Ele irá organizar também todos os seus imports.
Para que ele organize os imports corretamente, você precisa ter o FastAPI instalado localmente em seu ambiente, com o comando na seção acima usando `-e`.
### Formato dos imports
Tem outro _script_ que formata todos os imports e garante que você não tenha imports não utilizados:
<div class="termy">
```console
$ bash scripts/format-imports.sh
```
</div>
Como ele roda um comando após o outro, modificando e revertendo muitos arquivos, ele demora um pouco para concluir, então pode ser um pouco mais fácil utilizar `scripts/format.sh` frequentemente e `scripts/format-imports.sh` somente após "commitar uma branch".
## Documentação
Primeiro, tenha certeza de configurar seu ambiente como descrito acima, isso irá instalar todas as requisições.
A documentação usa <a href="https://www.mkdocs.org/" class="external-link" target="_blank">MkDocs</a>.
E existem ferramentas/_scripts_ extras para controlar as traduções em `./scripts/docs.py`.
/// tip
Você não precisa ver o código em `./scripts/docs.py`, você apenas o utiliza na linha de comando.
///
Toda a documentação está no formato Markdown no diretório `./docs/pt/`.
Muitos dos tutoriais tem blocos de código.
Na maioria dos casos, esse blocos de código são aplicações completas que podem ser rodadas do jeito que estão apresentados.
De fato, esses blocos de código não estão escritos dentro do Markdown, eles são arquivos Python dentro do diretório `./docs_src/`.
E esses arquivos Python são incluídos/injetados na documentação quando se gera o site.
### Testes para Documentação
A maioria dos testes na verdade rodam encima dos arquivos fonte na documentação.
Isso ajuda a garantir:
* Que a documentação esteja atualizada.
* Que os exemplos da documentação possam ser rodadas do jeito que estão apresentadas.
* A maior parte dos recursos é coberta pela documentação, garantida por cobertura de testes.
Durante o desenvolvimento local, existe um _script_ que constrói o site e procura por quaisquer mudanças, carregando na hora:
<div class="termy">
```console
$ 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
```
</div>
Isso irá servir a documentação em `http://127.0.0.1:8008`.
Desse jeito, você poderá editar a documentação/arquivos fonte e ver as mudanças na hora.
#### Typer CLI (opcional)
As instruções aqui mostram como utilizar _scripts_ em `./scripts/docs.py` com o programa `python` diretamente.
Mas você pode usar também <a href="https://typer.tiangolo.com/typer-cli/" class="external-link" target="_blank">Typer CLI</a>, e você terá auto-completação para comandos no seu terminal após instalar o _completion_.
Se você instalou Typer CLI, você pode instalar _completion_ com:
<div class="termy">
```console
$ typer --install-completion
zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.
```
</div>
### Aplicações e documentação ao mesmo tempo
Se você rodar os exemplos com, por exemplo:
<div class="termy">
```console
$ uvicorn tutorial001:app --reload
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
</div>
como Uvicorn utiliza por padrão a porta `8000`, a documentação na porta `8008` não dará conflito.
### Traduções
Ajuda com traduções É MUITO apreciada! E essa tarefa não pode ser concluída sem a ajuda da comunidade. 🌎 🚀
Aqui estão os passos para ajudar com as traduções.
#### Dicas e orientações
* Verifique sempre os <a href="https://github.com/fastapi/fastapi/pulls" class="external-link" target="_blank">_pull requests_ existentes</a> para a sua linguagem e faça revisões das alterações e aprove elas.
/// tip
Você pode <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request" class="external-link" target="_blank">adicionar comentários com sugestões de alterações</a> para _pull requests_ existentes.
Verifique as documentações sobre <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews" class="external-link" target="_blank">adicionar revisão ao _pull request_</a> para aprovação ou solicitação de alterações.
///
* Verifique em <a href="https://github.com/fastapi/fastapi/issues" class="external-link" target="_blank">_issues_</a> para ver se existe alguém coordenando traduções para a sua linguagem.
* Adicione um único _pull request_ por página traduzida. Isso tornará muito mais fácil a revisão para as outras pessoas.
Para as linguagens que eu não falo, vou esperar por várias pessoas revisarem a tradução antes de _mergear_.
* Você pode verificar também se há traduções para sua linguagem e adicionar revisão para elas, isso irá me ajudar a saber que a tradução está correta e eu possa _mergear_.
* Utilize os mesmos exemplos Python e somente traduza o texto na documentação. Você não tem que alterar nada no código para que funcione.
* Utilize as mesmas imagens, nomes de arquivo e links. Você não tem que alterar nada disso para que funcione.
* Para verificar o código de duas letras para a linguagem que você quer traduzir, você pode usar a <a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes" class="external-link" target="_blank">Lista de códigos ISO 639-1</a>.
#### Linguagem existente
Vamos dizer que você queira traduzir uma página para uma linguagem que já tenha traduções para algumas páginas, como o Espanhol.
No caso do Espanhol, o código de duas letras é `es`. Então, o diretório para traduções em Espanhol está localizada em `docs/es/`.
/// tip
A principal ("oficial") linguagem é o Inglês, localizado em `docs/en/`.
///
Agora rode o _servidor ao vivo_ para as documentações em Espanhol:
<div class="termy">
```console
// Use o comando "live" e passe o código da linguagem como um argumento de linha de comando
$ 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
```
</div>
Agora você pode ir em <a href="http://127.0.0.1:8008" class="external-link" target="_blank">http://127.0.0.1:8008</a> e ver suas mudanças ao vivo.
Se você procurar no site da documentação do FastAPI, você verá que toda linguagem tem todas as páginas. Mas algumas páginas não estão traduzidas e tem notificação sobre a falta da tradução.
Mas quando você rodar localmente como descrito acima, você somente verá as páginas que já estão traduzidas.
Agora vamos dizer que você queira adicionar uma tradução para a seção [Recursos](features.md){.internal-link target=_blank}.
* Copie o arquivo em:
```
docs/en/docs/features.md
```
* Cole ele exatamente no mesmo local mas para a linguagem que você quer traduzir, por exemplo:
```
docs/es/docs/features.md
```
/// tip
Observe que a única mudança na rota é o código da linguagem, de `en` para `es`.
///
* Agora abra o arquivo de configuração MkDocs para Inglês em:
```
docs/en/docs/mkdocs.yml
```
* Procure o lugar onde `docs/features.md` está localizado no arquivo de configuração. Algum lugar como:
```YAML hl_lines="8"
site_name: FastAPI
# Mais coisas
nav:
- FastAPI: index.md
- Languages:
- en: /
- es: /es/
- features.md
```
* Abra o arquivo de configuração MkDocs para a linguagem que você está editando, por exemplo:
```
docs/es/docs/mkdocs.yml
```
* Adicione no mesmo local que está no arquivo em Inglês, por exemplo:
```YAML hl_lines="8"
site_name: FastAPI
# Mais coisas
nav:
- FastAPI: index.md
- Languages:
- en: /
- es: /es/
- features.md
```
Tenha certeza que se existem outras entradas, a nova entrada com sua tradução esteja exatamente na mesma ordem como na versão em Inglês.
Se você for no seu navegador verá que agora a documentação mostra sua nova seção. 🎉
Agora você poderá traduzir tudo e ver como está toda vez que salva o arquivo.
#### Nova linguagem
Vamos dizer que você queira adicionar traduções para uma linguagem que ainda não foi traduzida, nem sequer uma página.
Vamos dizer que você queira adicionar tradução para Haitiano, e ainda não tenha na documentação.
Verificando o link acima, o código para "Haitiano" é `ht`.
O próximo passo é rodar o _script_ para gerar um novo diretório de tradução:
<div class="termy">
```console
// Use o comando new-lang, passe o código da linguagem como um argumento de linha de comando
$ python ./scripts/docs.py new-lang ht
Successfully initialized: docs/ht
Updating ht
Updating en
```
</div>
Agora você pode verificar em seu editor de código o mais novo diretório criado `docs/ht/`.
/// tip
Crie um primeiro _pull request_ com apenas isso, para iniciar a configuração da nova linguagem, antes de adicionar traduções.
Desse modo outros poderão ajudar com outras páginas enquanto você trabalha na primeira. 🚀
///
Inicie traduzindo a página principal, `docs/ht/index.md`.
Então você pode continuar com as instruções anteriores, para uma "Linguagem Existente".
##### Nova linguagem não suportada
Se quando rodar o _script_ do _servidor ao vivo_ você pega um erro sobre linguagem não suportada, alguma coisa como:
```
raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: partials/language/xx.html
```
Isso significa que o tema não suporta essa linguagem (nesse caso, com um código falso de duas letras `xx`).
Mas não se preocupe, você pode configurar o tema de linguagem para Inglês e então traduzir o conteúdo da documentação.
Se você precisar fazer isso, edite o `mkdocs.yml` para sua nova linguagem, teremos algo como:
```YAML hl_lines="5"
site_name: FastAPI
# Mais coisas
theme:
# Mais coisas
language: xx
```
Altere essa linguagem de `xx` (do seu código de linguagem) para `en`.
Então você poderá iniciar novamente o _servidor ao vivo_.
#### Pré-visualize o resultado
Quando você usa o _script_ em `./scripts/docs.py` com o comando `live` ele somente exibe os arquivos e traduções disponíveis para a linguagem atual.
Mas uma vez que você tenha concluído, você poderá testar tudo como se parecesse _online_.
Para fazer isso, primeiro construa toda a documentação:
<div class="termy">
```console
// Use o comando "build-all", isso leverá um tempinho
$ python ./scripts/docs.py build-all
Updating es
Updating en
Building docs for: en
Building docs for: es
Successfully built docs for: es
Copying en index.md to README.md
```
</div>
Isso gera toda a documentação em `./docs_build/` para cada linguagem. Isso inclui a adição de quaisquer arquivos com tradução faltando, com uma nota dizendo que "esse arquivo ainda não tem tradução". Mas você não tem que fazer nada com esse diretório.
Então ele constrói todos aqueles _sites_ independentes MkDocs para cada linguagem, combina eles, e gera a saída final em `./site/`.
Então você poderá "servir" eles com o comando `serve`:
<div class="termy">
```console
// Use o comando "serve" após rodar "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
```
</div>
## Testes
Tem um _script_ que você pode rodar localmente para testar todo o código e gerar relatórios de cobertura em HTML:
<div class="termy">
```console
$ bash scripts/test-cov-html.sh
```
</div>
Esse comando gera um diretório `./htmlcov/`, se você abrir o arquivo `./htmlcov/index.html` no seu navegador, poderá explorar interativamente as regiões de código que estão cobertas pelos testes, e observar se existe alguma região faltando.
### Testes no seu editor
Se você quer usar os testes integrados em seu editor adicione `./docs_src` na sua variável `PYTHONPATH`.
Por exemplo, no VS Code você pode criar um arquivo `.env` com:
```env
PYTHONPATH=./docs_src
```

496
docs/ru/docs/contributing.md
View File

@ -1,496 +0,0 @@
# Участие в разработке фреймворка
Возможно, для начала Вам стоит ознакомиться с основными способами [помочь FastAPI или получить помощь](help-fastapi.md){.internal-link target=_blank}.
## Разработка
Если Вы уже склонировали репозиторий и знаете, что Вам нужно более глубокое погружение в код фреймворка, то здесь представлены некоторые инструкции по настройке виртуального окружения.
### Виртуальное окружение с помощью `venv`
Находясь в нужной директории, Вы можете создать виртуальное окружение при помощи Python модуля `venv`.
<div class="termy">
```console
$ python -m venv env
```
</div>
Эта команда создаст директорию `./env/` с бинарными (двоичными) файлами Python, а затем Вы сможете скачивать и устанавливать необходимые библиотеки в изолированное виртуальное окружение.
### Активация виртуального окружения
Активируйте виртуально окружение командой:
//// tab | Linux, macOS
<div class="termy">
```console
$ source ./env/bin/activate
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
$ .\env\Scripts\Activate.ps1
```
</div>
////
//// tab | Windows Bash
Если Вы пользуетесь Bash для Windows (например: <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>):
<div class="termy">
```console
$ source ./env/Scripts/activate
```
</div>
////
Проверьте, что всё сработало:
//// tab | Linux, macOS, Windows Bash
<div class="termy">
```console
$ which pip
some/directory/fastapi/env/bin/pip
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
$ Get-Command pip
some/directory/fastapi/env/bin/pip
```
</div>
////
Если в терминале появится ответ, что бинарник `pip` расположен по пути `.../env/bin/pip`, значит всё в порядке. 🎉
Во избежание ошибок в дальнейших шагах, удостоверьтесь, что в Вашем виртуальном окружении установлена последняя версия `pip`:
<div class="termy">
```console
$ python -m pip install --upgrade pip
---> 100%
```
</div>
/// tip | Подсказка
Каждый раз, перед установкой новой библиотеки в виртуальное окружение при помощи `pip`, не забудьте активировать это виртуальное окружение.
Это гарантирует, что если Вы используете библиотеку, установленную этим пакетом, то Вы используете библиотеку из Вашего локального окружения, а не любую другую, которая может быть установлена глобально.
///
### pip
После активации виртуального окружения, как было указано ранее, введите следующую команду:
<div class="termy">
```console
$ pip install -r requirements.txt
---> 100%
```
</div>
Это установит все необходимые зависимости в локальное окружение для Вашего локального FastAPI.
#### Использование локального FastAPI
Если Вы создаёте Python файл, который импортирует и использует FastAPI,а затем запускаете его интерпретатором Python из Вашего локального окружения, то он будет использовать код из локального FastAPI.
И, так как при вводе вышеупомянутой команды был указан флаг `-e`, если Вы измените код локального FastAPI, то при следующем запуске этого файла, он будет использовать свежую версию локального FastAPI, который Вы только что изменили.
Таким образом, Вам не нужно "переустанавливать" Вашу локальную версию, чтобы протестировать каждое изменение.
### Форматировние
Скачанный репозиторий содержит скрипт, который может отформатировать и подчистить Ваш код:
<div class="termy">
```console
$ bash scripts/format.sh
```
</div>
Заодно он упорядочит Ваши импорты.
Чтобы он сортировал их правильно, необходимо, чтобы FastAPI был установлен локально в Вашей среде, с помощью команды из раздела выше, использующей флаг `-e`.
## Документация
Прежде всего, убедитесь, что Вы настроили своё окружение, как описано выше, для установки всех зависимостей.
Документация использует <a href="https://www.mkdocs.org/" class="external-link" target="_blank">MkDocs</a>.
Также существуют дополнительные инструменты/скрипты для работы с переводами в `./scripts/docs.py`.
/// tip | Подсказка
Нет необходимости заглядывать в `./scripts/docs.py`, просто используйте это в командной строке.
///
Вся документация имеет формат Markdown и расположена в директории `./docs/en/`.
Многие руководства содержат блоки кода.
В большинстве случаев эти блоки кода представляют собой вполне законченные приложения, которые можно запускать как есть.
На самом деле, эти блоки кода не написаны внутри Markdown, это Python файлы в директории `./docs_src/`.
И эти Python файлы включаются/вводятся в документацию при создании сайта.
### Тестирование документации
Фактически, большинство тестов запускаются с примерами исходных файлов в документации.
Это помогает убедиться, что:
* Документация находится в актуальном состоянии.
* Примеры из документации могут быть запущены как есть.
* Большинство функций описаны в документации и покрыты тестами.
Существует скрипт, который во время локальной разработки создаёт сайт и проверяет наличие любых изменений, перезагружая его в реальном времени:
<div class="termy">
```console
$ 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
```
</div>
Он запустит сайт документации по адресу: `http://127.0.0.1:8008`.
Таким образом, Вы сможете редактировать файлы с документацией или кодом и наблюдать изменения вживую.
#### Typer CLI (опционально)
Приведенная ранее инструкция показала Вам, как запускать скрипт `./scripts/docs.py` непосредственно через интерпретатор `python` .
Но также можно использовать <a href="https://typer.tiangolo.com/typer-cli/" class="external-link" target="_blank">Typer CLI</a>, что позволит Вам воспользоваться автозаполнением команд в Вашем терминале.
Если Вы установили Typer CLI, то для включения функции автозаполнения, введите эту команду:
<div class="termy">
```console
$ typer --install-completion
zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.
```
</div>
### Приложения и документация одновременно
Если Вы запускаете приложение, например так:
<div class="termy">
```console
$ uvicorn tutorial001:app --reload
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
</div>
По умолчанию Uvicorn будет использовать порт `8000` и не будет конфликтовать с сайтом документации, использующим порт `8008`.
### Переводы на другие языки
Помощь с переводами ценится КРАЙНЕ ВЫСОКО! И переводы не могут быть сделаны без помощи сообщества. 🌎 🚀
Ниже приведены шаги, как помочь с переводами.
#### Подсказки и инструкции
* Проверьте <a href="https://github.com/fastapi/fastapi/pulls" class="external-link" target="_blank">существующие пул-реквесты</a> для Вашего языка. Добавьте отзывы с просьбой внести изменения, если они необходимы, или одобрите их.
/// tip | Подсказка
Вы можете <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request" class="external-link" target="_blank">добавлять комментарии с предложениями по изменению</a> в существующие пул-реквесты.
Ознакомьтесь с документацией о <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews" class="external-link" target="_blank">добавлении отзыва к пул-реквесту</a>, чтобы утвердить его или запросить изменения.
///
* Проверьте <a href="https://github.com/fastapi/fastapi/issues" class="external-link" target="_blank">проблемы и вопросы</a>, чтобы узнать, есть ли кто-то, координирующий переводы для Вашего языка.
* Добавляйте один пул-реквест для каждой отдельной переведённой страницы. Это значительно облегчит другим его просмотр.
Для языков, которые я не знаю, прежде чем добавить перевод в основную ветку, я подожду пока несколько других участников сообщества проверят его.
* Вы также можете проверить, есть ли переводы для Вашего языка и добавить к ним отзыв, который поможет мне убедиться в правильности перевода. Тогда я смогу объединить его с основной веткой.
* Используйте те же самые примеры кода Python. Переводите только текст документации. Вам не нужно ничего менять, чтобы эти примеры работали.
* Используйте те же самые изображения, имена файлов и ссылки. Вы не должны менять ничего для сохранения работоспособности.
* Чтобы узнать 2-буквенный код языка, на который Вы хотите сделать перевод, Вы можете воспользоваться таблицей <a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes" class="external-link" target="_blank">Список кодов языков ISO 639-1</a>.
#### Существующий язык
Допустим, Вы хотите перевести страницу на язык, на котором уже есть какие-то переводы, например, на испанский.
Кодом испанского языка является `es`. А значит директория для переводов на испанский язык: `docs/es/`.
/// tip | Подсказка
Главный ("официальный") язык - английский, директория для него `docs/en/`.
///
Вы можете запустить сервер документации на испанском:
<div class="termy">
```console
// Используйте команду "live" и передайте код языка в качестве аргумента командной строки
$ 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
```
</div>
Теперь Вы можете перейти по адресу: <a href="http://127.0.0.1:8008" class="external-link" target="_blank">http://127.0.0.1:8008</a> и наблюдать вносимые Вами изменения вживую.
Если Вы посмотрите на сайт документации FastAPI, то увидите, что все страницы есть на каждом языке. Но некоторые страницы не переведены и имеют уведомление об отсутствующем переводе.
Но когда Вы запускаете сайт локально, Вы видите только те страницы, которые уже переведены.
Предположим, что Вы хотите добавить перевод страницы [Основные свойства](features.md){.internal-link target=_blank}.
* Скопируйте файл:
```
docs/en/docs/features.md
```
* Вставьте его точно в то же место, но в директорию языка, на который Вы хотите сделать перевод, например:
```
docs/es/docs/features.md
```
/// tip | Подсказка
Заметьте, что в пути файла мы изменили только код языка с `en` на `es`.
///
* Теперь откройте файл конфигурации MkDocs для английского языка, расположенный тут:
```
docs/en/mkdocs.yml
```
* Найдите в файле конфигурации место, где расположена строка `docs/features.md`. Похожее на это:
```YAML hl_lines="8"
site_name: FastAPI
# More stuff
nav:
- FastAPI: index.md
- Languages:
- en: /
- es: /es/
- features.md
```
* Откройте файл конфигурации MkDocs для языка, на который Вы переводите, например:
```
docs/es/mkdocs.yml
```
* Добавьте строку `docs/features.md` точно в то же место, как и в случае для английского, как-то так:
```YAML hl_lines="8"
site_name: FastAPI
# More stuff
nav:
- FastAPI: index.md
- Languages:
- en: /
- es: /es/
- features.md
```
Убедитесь, что при наличии других записей, новая запись с Вашим переводом находится точно в том же порядке, что и в английской версии.
Если Вы зайдёте в свой браузер, то увидите, что в документации стал отображаться Ваш новый раздел.🎉
Теперь Вы можете переводить эту страницу и смотреть, как она выглядит при сохранении файла.
#### Новый язык
Допустим, Вы хотите добавить перевод для языка, на который пока что не переведена ни одна страница.
Скажем, Вы решили сделать перевод для креольского языка, но его еще нет в документации.
Перейдите в таблицу кодов языков по ссылке указанной выше, где найдёте, что кодом креольского языка является `ht`.
Затем запустите скрипт, генерирующий директорию для переводов на новые языки:
<div class="termy">
```console
// Используйте команду new-lang и передайте код языка в качестве аргумента командной строки
$ python ./scripts/docs.py new-lang ht
Successfully initialized: docs/ht
Updating ht
Updating en
```
</div>
После чего Вы можете проверить в своем редакторе кода, что появился новый каталог `docs/ht/`.
/// tip | Подсказка
Создайте первый пул-реквест, который будет содержать только пустую директорию для нового языка, прежде чем добавлять переводы.
Таким образом, другие участники могут переводить другие страницы, пока Вы работаете над одной. 🚀
///
Начните перевод с главной страницы `docs/ht/index.md`.
В дальнейшем можно действовать, как указано в предыдущих инструкциях для "существующего языка".
##### Новый язык не поддерживается
Если при запуске скрипта `./scripts/docs.py live` Вы получаете сообщение об ошибке, что язык не поддерживается, что-то вроде:
```
raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: partials/language/xx.html
```
Сие означает, что тема не поддерживает этот язык (в данном случае с поддельным 2-буквенным кодом `xx`).
Но не стоит переживать. Вы можете установить языком темы английский, а затем перевести текст документации.
Если возникла такая необходимость, отредактируйте `mkdocs.yml` для Вашего нового языка. Это будет выглядеть как-то так:
```YAML hl_lines="5"
site_name: FastAPI
# More stuff
theme:
# More stuff
language: xx
```
Измените `xx` (код Вашего языка) на `en` и перезапустите сервер.
#### Предпросмотр результата
Когда Вы запускаете скрипт `./scripts/docs.py` с командой `live`, то будут показаны файлы и переводы для указанного языка.
Но когда Вы закончите, то можете посмотреть, как это будет выглядеть по-настоящему.
Для этого сначала создайте всю документацию:
<div class="termy">
```console
// Используйте команду "build-all", это займёт немного времени
$ python ./scripts/docs.py build-all
Updating es
Updating en
Building docs for: en
Building docs for: es
Successfully built docs for: es
Copying en index.md to README.md
```
</div>
Скрипт сгенерирует `./docs_build/` для каждого языка. Он добавит все файлы с отсутствующими переводами с пометкой о том, что "у этого файла еще нет перевода". Но Вам не нужно ничего делать с этим каталогом.
Затем он создаст независимые сайты MkDocs для каждого языка, объединит их и сгенерирует конечный результат на `./site/`.
После чего Вы сможете запустить сервер со всеми языками командой `serve`:
<div class="termy">
```console
// Используйте команду "serve" после того, как отработает команда "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
```
</div>
## Тесты
Также в репозитории есть скрипт, который Вы можете запустить локально, чтобы протестировать весь код и сгенерировать отчеты о покрытии тестами в HTML:
<div class="termy">
```console
$ bash scripts/test-cov-html.sh
```
</div>
Эта команда создаст директорию `./htmlcov/`, в которой будет файл `./htmlcov/index.html`. Открыв его в Вашем браузере, Вы можете в интерактивном режиме изучить, все ли части кода охвачены тестами.

472
docs/zh/docs/contributing.md
View File

@ -1,472 +0,0 @@
# 开发 - 贡献
首先，你可能想了解 [帮助 FastAPI 及获取帮助](help-fastapi.md){.internal-link target=_blank}的基本方式。
## 开发
如果你已经克隆了源码仓库，并且需要深入研究代码，下面是设置开发环境的指南。
### 通过 `venv` 管理虚拟环境
你可以使用 Python 的 `venv` 模块在一个目录中创建虚拟环境：
<div class="termy">
```console
$ python -m venv env
```
</div>
这将使用 Python 程序创建一个 `./env/` 目录，然后你将能够为这个隔离的环境安装软件包。
### 激活虚拟环境
使用以下方法激活新环境：
//// tab | Linux, macOS
<div class="termy">
```console
$ source ./env/bin/activate
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
$ .\env\Scripts\Activate.ps1
```
</div>
////
//// tab | Windows Bash
Or if you use Bash for Windows (e.g. <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>):
<div class="termy">
```console
$ source ./env/Scripts/activate
```
</div>
////
要检查操作是否成功，运行：
//// tab | Linux, macOS, Windows Bash
<div class="termy">
```console
$ which pip
some/directory/fastapi/env/bin/pip
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
$ Get-Command pip
some/directory/fastapi/env/bin/pip
```
</div>
////
如果显示 `pip` 程序文件位于 `env/bin/pip` 则说明激活成功。 🎉
确保虚拟环境中的 pip 版本是最新的，以避免后续步骤出现错误：
<div class="termy">
```console
$ python -m pip install --upgrade pip
---> 100%
```
</div>
/// tip
每一次你在该环境下使用 `pip` 安装了新软件包时，请再次激活该环境。
这样可以确保你在使用由该软件包安装的终端程序时使用的是当前虚拟环境中的程序，而不是其他的可能是全局安装的程序。
///
### pip
如上所述激活环境后：
<div class="termy">
```console
$ pip install -r requirements.txt
---> 100%
```
</div>
这将在虚拟环境中安装所有依赖和本地版本的 FastAPI。
#### 使用本地 FastAPI
如果你创建一个导入并使用 FastAPI 的 Python 文件，然后使用虚拟环境中的 Python 运行它，它将使用你本地的 FastAPI 源码。
并且如果你更改该本地 FastAPI 的源码，由于它是通过 `-e` 安装的，当你再次运行那个 Python 文件，它将使用你刚刚编辑过的最新版本的 FastAPI。
这样，你不必再去重新"安装"你的本地版本即可测试所有更改。
/// note | 技术细节
仅当你使用此项目中的 `requirements.txt` 安装而不是直接使用 `pip install fastapi` 安装时，才会发生这种情况。
这是因为在 `requirements.txt` 中，本地的 FastAPI 是使用“可编辑” （`-e`）选项安装的
///
### 格式化
你可以运行下面的脚本来格式化和清理所有代码：
<div class="termy">
```console
$ bash scripts/format.sh
```
</div>
它还会自动对所有导入代码进行排序整理。
为了使整理正确进行，你需要在当前环境中安装本地的 FastAPI，即在运行上述段落中的命令时添加 `-e`。
## 文档
首先，请确保按上述步骤设置好环境，这将安装所有需要的依赖。
### 实时文档
在本地开发时，可以使用该脚本构建站点并检查所做的任何更改，并实时重载：
<div class="termy">
```console
$ 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
```
</div>
文档服务将运行在 `http://127.0.0.1:8008`。
这样，你可以编辑文档 / 源文件并实时查看更改。
/// tip
或者你也可以手动执行和该脚本一样的操作
进入语言目录，如果是英文文档，目录则是 `docs/en/`:
```console
$ cd docs/en/
```
在该目录执行 `mkdocs` 命令
```console
$ mkdocs serve --dev-addr 8008
```
///
#### Typer CLI （可选）
本指引向你展示了如何直接用 `python` 运行 `./scripts/docs.py` 中的脚本。
但你也可以使用 <a href="https://typer.tiangolo.com/typer-cli/" class="external-link" target="_blank">Typer CLI</a>，而且在安装了补全功能后，你将可以在终端中对命令进行自动补全。
如果你已经安装 Typer CLI ，则可以使用以下命令安装自动补全功能：
<div class="termy">
```console
$ typer --install-completion
zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.
```
</div>
### 文档架构
文档使用 <a href="https://www.mkdocs.org/" class="external-link" target="_blank">MkDocs</a> 生成。
在 `./scripts/docs.py` 中还有额外工具 / 脚本来处理翻译。
/// tip
你不需要去了解 `./scripts/docs.py` 中的代码，只需在命令行中使用它即可。
///
所有文档均在 `./docs/en/` 目录中以 Markdown 文件格式保存。
许多的教程中都有一些代码块，大多数情况下，这些代码是可以直接运行的，因为这些代码不是写在 Markdown 文件里的，而是写在 `./docs_src/` 目录中的 Python 文件里。
在生成站点的时候，这些 Python 文件会被打包进文档中。
### 测试文档
大多数的测试实际上都是针对文档中的示例源文件运行的。
这有助于确保：
* 文档始终是最新的。
* 文档示例可以直接运行。
* 绝大多数特性既在文档中得以阐述，又通过测试覆盖进行保障。
### 应用和文档同时运行
如果你使用以下方式运行示例程序：
<div class="termy">
```console
$ uvicorn tutorial001:app --reload
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
</div>
由于 Uvicorn 默认使用 `8000` 端口 ，因此运行在 `8008` 端口上的文档不会与之冲突。
### 翻译
**非常感谢**你能够参与文档的翻译！这项工作需要社区的帮助才能完成。 🌎 🚀
以下是参与帮助翻译的步骤。
#### 建议和指南
* 在当前 <a href="https://github.com/fastapi/fastapi/pulls" class="external-link" target="_blank">已有的 pull requests</a> 中查找你使用的语言，添加要求修改或同意合并的评审意见。
/// tip
你可以为已有的 pull requests <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request" class="external-link" target="_blank">添加包含修改建议的评论</a>。
详情可查看关于 <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews" class="external-link" target="_blank">添加 pull request 评审意见</a> 以同意合并或要求修改的文档。
///
* 检查在 <a href="https://github.com/fastapi/fastapi/discussions/categories/translations" class="external-link" target="_blank">GitHub Discussion</a> 是否有关于你所用语言的协作翻译。 如果有，你可以订阅它，当有一条新的 PR 请求需要评审时，系统会自动将其添加到讨论中，你也会收到对应的推送。
* 每翻译一个页面新增一个 pull request。这将使其他人更容易对其进行评审。
对于我（译注：作者使用西班牙语和英语）不懂的语言，我将在等待其他人评审翻译之后将其合并。
* 你还可以查看是否有你所用语言的翻译，并对其进行评审，这将帮助我了解翻译是否正确以及能否将其合并。
* 可以在 <a href="https://github.com/fastapi/fastapi/discussions/categories/translations" class="external-link" target="_blank">GitHub Discussions</a> 中查看。
* 也可以在现有 PR 中通过你使用的语言标签来筛选对应的 PR，举个例子，对于西班牙语，标签是 <a href="https://github.com/fastapi/fastapi/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc+label%3Alang-es+label%3A%22awaiting+review%22" class="external-link" target="_blank">`lang-es`</a>。
* 请使用相同的 Python 示例，且只需翻译文档中的文本，不用修改其它东西。
* 请使用相同的图片、文件名以及链接地址，不用修改其它东西。
* 你可以从 <a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes" class="external-link" target="_blank">ISO 639-1 代码列表</a> 表中查找你想要翻译语言的两位字母代码。
#### 已有的语言
假设你想将某个页面翻译成已经翻译了一些页面的语言，例如西班牙语。
对于西班牙语来说，它的两位字母代码是 `es`。所以西班牙语翻译的目录位于 `docs/es/`。
/// tip
默认语言是英语，位于 `docs/en/`目录。
///
现在为西班牙语文档运行实时服务器：
<div class="termy">
```console
// 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
```
</div>
/// tip
或者你也可以手动执行和该脚本一样的操作
进入语言目录，对于西班牙语的翻译，目录是 `docs/es/`:
```console
$ cd docs/es/
```
在该目录执行 `mkdocs` 命令
```console
$ mkdocs serve --dev-addr 8008
```
///
现在你可以访问 <a href="http://127.0.0.1:8008" class="external-link" target="_blank">http://127.0.0.1:8008</a> 实时查看你所做的更改。
如果你查看 FastAPI 的线上文档网站，会看到每种语言都有所有的文档页面，但是某些页面并未被翻译并且会有一处关于缺少翻译的提示。（但是当你像上面这样在本地运行文档时，你只会看到已经翻译的页面。）
现在假设你要为 [Features](features.md){.internal-link target=_blank} 章节添加翻译。
* 复制下面的文件：
```
docs/en/docs/features.md
```
* 粘贴到你想要翻译语言目录的相同位置，比如：
```
docs/es/docs/features.md
```
/// tip
注意路径和文件名的唯一变化是语言代码，从 `en` 更改为 `es`。
///
回到浏览器你就可以看到刚刚更新的章节了。🎉
现在，你可以翻译这些内容并在保存文件后进行预览。
#### 新语言
假设你想要为尚未有任何页面被翻译的语言添加翻译。
假设你想要添加克里奥尔语翻译，而且文档中还没有该语言的翻译。
点击上面提到的“ISO 639-1 代码列表”链接，可以查到“克里奥尔语”的代码为 `ht`。
下一步是运行脚本以生成新的翻译目录：
<div class="termy">
```console
// Use the command new-lang, pass the language code as a CLI argument
$ python ./scripts/docs.py new-lang ht
Successfully initialized: docs/ht
```
</div>
现在，你可以在编辑器中查看新创建的目录 `docs/ht/`。
这条命令会生成一个从 `en` 版本继承了所有属性的配置文件 `docs/ht/mkdocs.yml`:
```yaml
INHERIT: ../en/mkdocs.yml
```
/// tip
你也可以自己手动创建包含这些内容的文件。
///
这条命令还会生成一个文档主页 `docs/ht/index.md`，你可以从这个文件开始翻译。
然后，你可以根据上面的"已有语言"的指引继续进行翻译。
翻译完成后，你就可以用 `docs/ht/mkdocs.yml` 和 `docs/ht/index.md` 发起 PR 了。🎉
#### 预览结果
你可以执行 `./scripts/docs.py live` 命令来预览结果（或者 `mkdocs serve`）。
但是当你完成翻译后，你可以像在线上展示一样测试所有内容，包括所有其他语言。
为此，首先构建所有文档：
<div class="termy">
```console
// 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
```
</div>
这样会对每一种语言构建一个独立的文档站点，并最终把这些站点全部打包输出到 `./site/` 目录。
然后你可以使用命令 `serve` 来运行生成的站点：
<div class="termy">
```console
// 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
```
</div>
## 测试
你可以在本地运行下面的脚本来测试所有代码并生成 HTML 格式的覆盖率报告：
<div class="termy">
```console
$ bash scripts/test-cov-html.sh
```
</div>
该命令生成了一个 `./htmlcov/` 目录，如果你在浏览器中打开 `./htmlcov/index.html` 文件，你可以交互式地浏览被测试所覆盖的代码区块，并注意是否缺少了任何区块。

1
scripts/docs.py
View File

@ -35,6 +35,7 @@ non_translated_sections = [
"newsletter.md",
"management-tasks.md",
"management.md",
"contributing.md",
]
docs_path = Path("docs")

Write Preview
Loading…
Cancel
Save