:memo: Add docs for debugging

diff --git a/docs/img/tutorial/debugging/image01.png b/docs/img/tutorial/debugging/image01.png
new file mode 100644 (file)
index 0000000..ae34c8f
Binary files /dev/null and b/docs/img/tutorial/debugging/image01.png differ

diff --git a/docs/src/debugging/tutorial001.py b/docs/src/debugging/tutorial001.py
new file mode 100644 (file)
index 0000000..3de21d2
--- /dev/null
+++ b/docs/src/debugging/tutorial001.py
@@ -0,0 +1,15 @@
+import uvicorn
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/")
+def root():
+    a = "a"
+    b = "b" + a
+    return {"hello world": b}
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)

diff --git a/docs/tutorial/debugging.md b/docs/tutorial/debugging.md
new file mode 100644 (file)
index 0000000..4de6b07
--- /dev/null
+++ b/docs/tutorial/debugging.md
@@ -0,0 +1,84 @@
+You can connect the debugger in your editor, for example with Visual Studio Code or PyCharm.
+
+## Call `uvicorn`
+
+In your FastAPI application, import and run `uvicorn` directly:
+
+```Python hl_lines="1 15"
+{!./src/debugging/tutorial001.py!}
+```
+
+### About `__name__ == "__main__"`
+
+The main purpose of the `__name__ == "__main__"` is to have some code that is executed when your file is called with:
+
+```bash
+python myapp.py
+```
+
+but is not called when another file imports it, like in:
+
+```Python
+from myapp import app
+```
+
+#### More details
+
+Let's say your file is named `myapp.py`.
+
+If you run it with:
+
+```bash
+python myapp.py
+```
+
+then the internal variable `__name__` in your file, created automatically by Python, will have as value the string `"__main__"`.
+
+So, the section:
+
+```Python
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+will run.
+
+---
+
+This won't happen if you import that module (file).
+
+So, if you have another file `importer.py` with:
+
+```Python
+from myapp import app
+
+# Some more code
+```
+
+in that case, the automatic variable inside of `myapp.py` will not have the variable `__name__` with a value of `"__main__"`.
+
+So, the line:
+
+```Python
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+will not be executed.
+
+## Run your code with your debugger
+
+Because you are running the Uvicorn server directly from your code, you can call your Python program (your FastAPI application) directly form the debugger.
+
+---
+
+For example, in Visual Studio Code, you can:
+
+* Go to the "Debug" panel.
+* "Add configuration...".
+* Select "Python"
+* Run the debugger with the option "`Python: Current File (Integrated Terminal)`".
+
+It will then start the server with your **FastAPI** code, stop at your breakpoints, etc.
+
+Here's how it might look:
+
+<img src="/img/tutorial/debugging/image01.png">

diff --git a/mkdocs.yml b/mkdocs.yml
index 0859af3a7e405ede7af6c20ac8027b3db081cc2b..87361bcfc4a31cd2ba3e46032c0c3bfd4ecfad62 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -62,6 +62,7 @@ nav:
         - Sub Applications - Behind a Proxy: 'tutorial/sub-applications-proxy.md'
         - Application Configuration: 'tutorial/application-configuration.md'
         - GraphQL: 'tutorial/graphql.md'
+        - Debugging: 'tutorial/debugging.md'
     - Concurrency and async / await: 'async.md'
     - Deployment: 'deployment.md'
     - Project Generation - Template: 'project-generation.md'