Generate docs for Typer apps

README.md

@@ -137,7 +137,7 @@ if __name__ == "__main__":
 
 You can also remove it if you are calling that script only with **Typer CLI** (using the `typer` command).
 
-## What can it run
+## Run other files
 
 **Typer CLI** can run any script with **Typer**, but the script doesn't even have to use **Typer** at all.
 
@@ -167,6 +167,25 @@ Hello Camila
 
 And it will also have completion for things like the `--name` **CLI Option**.
 
+## Run a package or module
+
+Instead of a file path you can pass a module (possibly in a package) to import.
+
+For example:
+
+```console
+$ typer my_package.main run --help
+Usage: typer run [OPTIONS]
+
+Options:
+  --name TEXT
+  --help       Show this message and exit.
+
+$ typer my_package.main run --name Camila
+
+Hello Camila
+```
+
 ## Options
 
 You can specify the following **CLI Options**:
@@ -185,6 +204,33 @@ When your run a script with the **Typer CLI** (the `typer` command) it will use
 * A function in a variable with a name of `main`, `cli`, or `app`.
 * The first function in the file, with any name.
 
+## Generate docs
+
+**Typer CLI** can also generate Markdown documentation for your **Typer** application.
+
+You can use the subcommand `utils`.
+
+And then the subcommand `docs`.
+
+For example:
+
+```console
+$ typer some_script.py utils docs
+```
+
+**Options**:
+
+* `--name TEXT`: The name of the CLI program to use in docs.
+* `--output FILE`: An output file to write docs to, like README.md.
+
+For example:
+
+```console
+$ typer my_package.main utils docs --name myapp --output README.md
+
+Docs saved to: README.md
+```
+
 ## License
 
 This project is licensed under the terms of the MIT license.

tests/assets/multi_app.py

@@ -6,19 +6,28 @@
 
 
 @sub_app.command()
-def hello():
-    typer.echo("sub hello")
+def hello(name: str = "World"):
+    """
+    Say Hello
+    """
+    typer.echo(f"Hello {name}")
 
 
 @sub_app.command()
 def bye():
+    """
+    Say bye
+    """
     typer.echo("sub bye")
 
 
-app = typer.Typer()
+app = typer.Typer(help="Demo App", epilog="The end")
 app.add_typer(sub_app, name="sub")
 
 
 @app.command()
 def top():
+    """
+    Top command
+    """
     typer.echo("top")

tests/assets/multiapp-docs.md

@@ -0,0 +1,82 @@
+# `multiapp`
+
+Demo App
+
+**Usage**:
+
+```console
+$ multiapp [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--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.
+
+The end
+
+**Commands**:
+
+* `sub`
+* `top`: Top command
+
+## `multiapp sub`
+
+**Usage**:
+
+```console
+$ multiapp sub [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `bye`: Say bye
+* `hello`: Say Hello
+
+### `multiapp sub bye`
+
+Say bye
+
+**Usage**:
+
+```console
+$ multiapp sub bye [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+### `multiapp sub hello`
+
+Say Hello
+
+**Usage**:
+
+```console
+$ multiapp sub hello [OPTIONS]
+```
+
+**Options**:
+
+* `--name TEXT`
+* `--help`: Show this message and exit.
+
+## `multiapp top`
+
+Top command
+
+**Usage**:
+
+```console
+$ multiapp top [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.

tests/test_doc.py

@@ -0,0 +1,97 @@
+import subprocess
+from pathlib import Path
+
+
+def test_doc():
+    result = subprocess.run(
+        [
+            "coverage",
+            "run",
+            "-m",
+            "typer_cli",
+            "tests.assets.multi_app",
+            "utils",
+            "docs",
+            "--name",
+            "multiapp",
+        ],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        encoding="utf-8",
+    )
+    docs_path: Path = Path(__file__).parent / "assets/multiapp-docs.md"
+    docs = docs_path.read_text()
+    assert docs in result.stdout
+
+
+def test_doc_output(tmp_path: Path):
+    out_file: Path = tmp_path / "out.md"
+    result = subprocess.run(
+        [
+            "coverage",
+            "run",
+            "-m",
+            "typer_cli",
+            "tests.assets.multi_app",
+            "utils",
+            "docs",
+            "--name",
+            "multiapp",
+            "--output",
+            str(out_file),
+        ],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        encoding="utf-8",
+    )
+    docs_path: Path = Path(__file__).parent / "assets/multiapp-docs.md"
+    docs = docs_path.read_text()
+    written_docs = out_file.read_text()
+    assert docs in written_docs
+    assert "Docs saved to:" in result.stdout
+
+
+def test_doc_not_existing():
+    result = subprocess.run(
+        ["coverage", "run", "-m", "typer_cli", "no_typer", "utils", "docs"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        encoding="utf-8",
+    )
+    assert "Could not import as Python module:" in result.stderr
+
+
+def test_doc_no_typer():
+    result = subprocess.run(
+        [
+            "coverage",
+            "run",
+            "-m",
+            "typer_cli",
+            "tests/assets/empty_script.py",
+            "utils",
+            "docs",
+        ],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        encoding="utf-8",
+    )
+    assert "No Typer app found" in result.stderr
+
+
+def test_doc_file_not_existing():
+    result = subprocess.run(
+        [
+            "coverage",
+            "run",
+            "-m",
+            "typer_cli",
+            "assets/not_existing.py",
+            "utils",
+            "docs",
+        ],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        encoding="utf-8",
+    )
+    assert "Not a valid file or Python module:" in result.stderr

tests/test_help.py

@@ -18,4 +18,4 @@ def test_not_python():
         stderr=subprocess.PIPE,
         encoding="utf-8",
     )
-    assert "Could not import as Python the file" in result.stderr
+    assert "Could not import as Python file" in result.stderr

tests/test_multi_app.py

@@ -94,7 +94,7 @@ def test_script_sub_hello():
         stderr=subprocess.PIPE,
         encoding="utf-8",
     )
-    assert "sub hello" in result.stdout
+    assert "Hello World" in result.stdout
 
 
 def test_script_sub_bye():

tests/test_multi_app_sub.py

@@ -40,4 +40,4 @@ def test_script():
         stderr=subprocess.PIPE,
         encoding="utf-8",
     )
-    assert "sub hello" in result.stdout
+    assert "Hello World" in result.stdout

tests/test_not_python.py

@@ -8,4 +8,4 @@ def test_not_python():
         stderr=subprocess.PIPE,
         encoding="utf-8",
     )
-    assert "Could not import as Python the file" in result.stderr
+    assert "Could not import as Python file" in result.stderr

tests/test_sub.py

@@ -106,4 +106,4 @@ def test_not_python():
         stderr=subprocess.PIPE,
         encoding="utf-8",
     )
-    assert "Could not import as Python the file" in result.stderr
+    assert "Could not import as Python file" in result.stderr