From cf75cada76d2321efab48d1cf4c0105912e74868 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com>
Date: Sat, 28 Dec 2019 14:24:54 +0100
Subject: [PATCH] :memo: Update First Steps to include how to document in a
 docstring

---
 docs/src/first_steps/tutorial006.py | 17 +++++++++++
 docs/tutorial/first-steps.md        | 44 +++++++++++++++++++++++++++--
 2 files changed, 59 insertions(+), 2 deletions(-)
 create mode 100644 docs/src/first_steps/tutorial006.py

diff --git a/docs/src/first_steps/tutorial006.py b/docs/src/first_steps/tutorial006.py
new file mode 100644
index 0000000..d373bbc
--- /dev/null
+++ b/docs/src/first_steps/tutorial006.py
@@ -0,0 +1,17 @@
+import typer
+
+
+def main(name: str, lastname: str = "", formal: bool = False):
+    """
+    Say hi to NAME, optionally with a --lastname.
+
+    If --formal is used, say hi very formally.
+    """
+    if formal:
+        typer.echo(f"Good day Ms. {name} {lastname}.")
+    else:
+        typer.echo(f"Hello {name} {lastname}")
+
+
+if __name__ == "__main__":
+    typer.run(main)
diff --git a/docs/tutorial/first-steps.md b/docs/tutorial/first-steps.md
index 9e0fa70..9231626 100644
--- a/docs/tutorial/first-steps.md
+++ b/docs/tutorial/first-steps.md
@@ -22,10 +22,12 @@ Hello World
 // Now check the --help
 $ python main.py --help
 
-Usage: main.py [OPTIONS]
+Usage: tryit.py [OPTIONS]
 
 Options:
-  --help  Show this message and exit.
+  --install-completion  Install completion for the current shell.
+  --show-completion     Show completion for the current shell, to copy it or customize the installation.
+  --help                Show this message and exit.
 ```
 
 </div>
@@ -302,6 +304,44 @@ Hello Camila Gutiérrez
 
 </div>
 
+## Document your CLI app
+
+If you add a <abbr title="a multi-line string as the first expression inside a function (not assigned to any variable) used for documentation">docstring</abbr> to your function it will be used in the help text:
+
+```Python hl_lines="5 6 7 8 9"
+{!./src/first_steps/tutorial006.py!}
+```
+
+Now see it with the `--help` option:
+
+<div class="termy">
+
+```console
+$ python main.py --help
+
+Usage: tutorial006.py [OPTIONS] NAME
+
+  Say hi to NAME, optionally with a --lastname.
+
+  If --formal is used, say hi very formally.
+
+Options:
+  --lastname TEXT
+  --formal / --no-formal
+  --install-completion    Install completion for the current shell.
+  --show-completion       Show completion for the current shell, to copy it or customize the installation.
+  --help                  Show this message and exit.
+```
+
+</div>
+
+!!! tip
+    You should document the *CLI arguments* in the docstring.
+
+    There is another place to document the *CLI options* that will show up next to them in the help text as with `--install-completion` or `--help`, you will learn that later in the tutorial.
+
+    But *CLI arguments* are normally used for the most necessary things, so you should document them here in the *docstring*.
+
 ## Arguments, options, parameters, optional, required
 
 Be aware that these terms refer to multiple things depending on the context, and sadly, those "contexts" mix frequently, so it's easy to get confused.