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. ``` @@ -302,6 +304,44 @@ Hello Camila GutiƩrrez +## Document your CLI app + +If you add a docstring 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: + +
+ +```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. +``` + +
+ +!!! 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.