@@ -101,7 +101,7 @@ $ python -m pip install --upgrade pip
This makes sure that if you use a terminal program installed by that package, you use the one from your local environment and not any other that could be installed globally.
-### pip
+### Install requirements using pip
After activating the environment as described above:
@@ -117,20 +117,20 @@ $ pip install -r requirements.txt
It will install all the dependencies and your local FastAPI in your local environment.
-#### Using your local FastAPI
+### Using your local FastAPI
-If you create a Python file that imports and uses FastAPI, and run it with the Python from your local environment, it will use your local FastAPI source code.
+If you create a Python file that imports and uses FastAPI, and run it with the Python from your local environment, it will use your cloned local FastAPI source code.
And if you update that local FastAPI source code when you run that Python file again, it will use the fresh version of FastAPI you just edited.
That way, you don't have to "install" your local version to be able to test every change.
!!! note "Technical Details"
- This only happens when you install using this included `requirements.txt` instead of installing `pip install fastapi` directly.
+ This only happens when you install using this included `requirements.txt` instead of running `pip install fastapi` directly.
- That is because inside of the `requirements.txt` file, the local version of FastAPI is marked to be installed in "editable" mode, with the `-e` option.
+ That is because inside the `requirements.txt` file, the local version of FastAPI is marked to be installed in "editable" mode, with the `-e` option.
-### Format
+### Format the code
There is a script that you can run that will format and clean all your code:
@@ -227,15 +227,13 @@ And those Python files are included/injected in the documentation when generatin
Most of the tests actually run against the example source files in the documentation.
-This helps making sure that:
+This helps to make sure that:
-* The documentation is up to date.
+* The documentation is up-to-date.
* The documentation examples can be run as is.
* Most of the features are covered by the documentation, ensured by test coverage.
-
-
-### Apps and docs at the same time
+#### Apps and docs at the same time
If you run the examples with, e.g.:
@@ -259,7 +257,9 @@ Here are the steps to help with translations.
#### Tips and guidelines
-* Check the currently
existing pull requests for your language and add reviews requesting changes or approving them.
+* Check the currently
existing pull requests for your language. You can filter the pull requests by the ones with the label for your language. For example, for Spanish, the label is
`lang-es`.
+
+* Review those pull requests, requesting changes or approving them. For the languages I don't speak, I'll wait for several others to review the translation before merging.
!!! tip
You can
add comments with change suggestions to existing pull requests.
@@ -268,19 +268,9 @@ Here are the steps to help with translations.
* Check if there's a
GitHub Discussion to coordinate translations for your language. You can subscribe to it, and when there's a new pull request to review, an automatic comment will be added to the discussion.
-* Add a single pull request per page translated. That will make it much easier for others to review it.
+* If you translate pages, add a single pull request per page translated. That will make it much easier for others to review it.
-For the languages I don't speak, I'll wait for several others to review the translation before merging.
-
-* You can also check if there are translations for your language and add a review to them, that will help me know that the translation is correct and I can merge it.
- * You could check in the
GitHub Discussions for your language.
- * Or you can filter the existing PRs by the ones with the label for your language, for example, for Spanish, the label is
`lang-es`.
-
-* Use the same Python examples and only translate the text in the docs. You don't have to change anything for this to work.
-
-* Use the same images, file names, and links. You don't have to change anything for it to work.
-
-* To check the 2-letter code for the language you want to translate you can use the table
List of ISO 639-1 codes.
+* To check the 2-letter code for the language you want to translate, you can use the table
List of ISO 639-1 codes.
#### Existing language
@@ -323,7 +313,7 @@ $ python ./scripts/docs.py live es
Now you can go to
http://127.0.0.1:8008 and see your changes live.
-You will see that every language has all the pages. But some pages are not translated and have a notification about the missing translation.
+You will see that every language has all the pages. But some pages are not translated and have an info box at the top, about the missing translation.
Now let's say that you want to add a translation for the section [Features](features.md){.internal-link target=_blank}.
@@ -342,7 +332,7 @@ docs/es/docs/features.md
!!! tip
Notice that the only change in the path and file name is the language code, from `en` to `es`.
-If you go to your browser you will see that now the docs show your new section. 🎉
+If you go to your browser you will see that now the docs show your new section (the info box at the top is gone). 🎉
Now you can translate it all and see how it looks as you save the file.
@@ -386,7 +376,7 @@ You can make the first pull request with those two files, `docs/ht/mkdocs.yml` a
#### Preview the result
-You can use the `./scripts/docs.py` with the `live` command to preview the results (or `mkdocs serve`).
+As already mentioned above, you can use the `./scripts/docs.py` with the `live` command to preview the results (or `mkdocs serve`).
Once you are done, you can also test it all as it would look online, including all the other languages.
@@ -423,6 +413,25 @@ Serving at: http://127.0.0.1:8008