From bc4709cc9de09d9ee95cee66e04b8cf8f148cfe7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com>
Date: Thu, 2 Jan 2020 19:09:36 +0100
Subject: [PATCH] :memo: Add docs for launching applications

---
 docs/src/launch/tutorial001.py | 10 +++++++
 docs/src/launch/tutorial002.py | 21 +++++++++++++++
 docs/tutorial/launch.md        | 48 ++++++++++++++++++++++++++++++++++
 mkdocs.yml                     |  1 +
 4 files changed, 80 insertions(+)
 create mode 100644 docs/src/launch/tutorial001.py
 create mode 100644 docs/src/launch/tutorial002.py
 create mode 100644 docs/tutorial/launch.md

diff --git a/docs/src/launch/tutorial001.py b/docs/src/launch/tutorial001.py
new file mode 100644
index 0000000..892faa2
--- /dev/null
+++ b/docs/src/launch/tutorial001.py
@@ -0,0 +1,10 @@
+import typer
+
+
+def main():
+    typer.echo("Opening Typer's docs")
+    typer.launch("https://typer.tiangolo.com")
+
+
+if __name__ == "__main__":
+    typer.run(main)
diff --git a/docs/src/launch/tutorial002.py b/docs/src/launch/tutorial002.py
new file mode 100644
index 0000000..5ef13ec
--- /dev/null
+++ b/docs/src/launch/tutorial002.py
@@ -0,0 +1,21 @@
+from pathlib import Path
+
+import typer
+
+APP_NAME = "my-super-cli-app"
+
+
+def main():
+    app_dir = typer.get_app_dir(APP_NAME)
+    app_dir_path = Path(app_dir)
+    app_dir_path.mkdir(parents=True, exist_ok=True)
+    config_path: Path = Path(app_dir) / "config.json"
+    if not config_path.is_file():
+        config_path.write_text('{"version": "1.0.0"}')
+    config_file_str = str(config_path)
+    typer.echo("Opening config directory")
+    typer.launch(config_file_str, locate=True)
+
+
+if __name__ == "__main__":
+    typer.run(main)
diff --git a/docs/tutorial/launch.md b/docs/tutorial/launch.md
new file mode 100644
index 0000000..3a64670
--- /dev/null
+++ b/docs/tutorial/launch.md
@@ -0,0 +1,48 @@
+You can launch applications from your CLI program with `typer.launch()`.
+
+It will launch the appropriate application depending on the URL or file type you pass it:
+
+```Python hl_lines="6"
+{!./src/launch/tutorial001.py!}
+```
+
+Check it:
+
+<div class="termy">
+
+```console
+$ python main.py
+
+Opening Typer docs
+
+// Opens browser with Typer's docs
+```
+
+</div>
+
+## Locating a file
+
+You can also make the operating system open the file browser indicating where a file is located with `locate=True`:
+
+```Python hl_lines="17"
+{!./src/launch/tutorial002.py!}
+```
+
+!!! tip
+    The rest of the code in this example is just making sure the app directory exists and creating the config file.
+    
+    But the most important part is the `typer.launch(config_file_str, locate=True)` with the argument `locate=True`.
+
+Check it:
+
+<div class="termy">
+
+```console
+$ python main.py
+
+Opening config directory
+
+// Opens a file browser indicating where the config file is located
+```
+
+</div>
diff --git a/mkdocs.yml b/mkdocs.yml
index c462744..b5aaba4 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -50,6 +50,7 @@ nav:
         - Ask with Prompt: 'tutorial/prompt.md'
         - Progress Bar: 'tutorial/progressbar.md'
         - CLI Application Directory: 'tutorial/app-dir.md'
+        - Launching Applications: 'tutorial/launch.md'
     - Alternatives, Inspiration and Comparisons: 'alternatives.md'
     - Help Typer - Get Help: 'help-typer.md'
     - Development - Contributing: 'contributing.md'