Document parse() in api docs (#56)

docs/api/functions.md

@@ -26,6 +26,40 @@ Given a function, or a container of functions `obj`, parse its arguments from th
 | Type | Description |
 |------|-------------|
 | `Any` | The return value of the function `obj`, or the subcommand of `obj` if it is a list or dict. |
+
+
+
+## `parse()`
+
+```python
+def parse(
+    cls: type[~T],
+    args: list[str] | None = None,
+    brief: str = '',
+    caught: bool = True,
+) -> ~T
+```
+
+Given a class `cls`, parse arguments from the command-line according to the class definition and construct an instance.
+
+### Parameters: <!-- {docsify-ignore} -->
+
+| Name | Type | Description | Default |
+|------|------|-------------|---------|
+| `cls` | <span class="codey"> type[~T] </span> | The class to parse the arguments for and construct an instance of. | _required_ |
+| `args` | <span class="codey"> list[str] \| None </span> | The arguments to parse. If None, uses the arguments from the command-line (i.e. sys.argv). | `None` |
+| `brief` | <span class="codey"> str </span> | The brief description of the parser. This is used to display a brief when --help is invoked. | `''` |
+| `caught` | <span class="codey"> bool </span> | Whether to catch and print errors instead of raising. This is used to display a more presentable output when a parse error occurs instead of the default traceback. | `True` |
+
+
+### Returns: <!-- {docsify-ignore} -->
+
+| Type | Description |
+|------|-------------|
+| `~T` | An instance of the class `cls`. |
+
+
+
 ## `register()`
 
 ```python

docs/make_api.py

@@ -3,7 +3,7 @@
 from collections import abc
 from typing import Any, Callable, TextIO, Union, get_args, get_origin
 
-from startle import register, start
+from startle import parse, register, start
 from startle.inspect import _parse_func_docstring
 
 
@@ -76,7 +76,7 @@ def func_api(func: Callable, file: TextIO):
     for param in sig.parameters.values():
         maybe_default = ""
         if param.default is not inspect.Parameter.empty:
-            maybe_default = f" = {param.default}"
+            maybe_default = f" = {repr(param.default)}"
         print(
             f"    {param.name}: {_shorten_type_annotation(param.annotation)}{maybe_default},",
             file=file,
@@ -101,7 +101,7 @@ def func_api(func: Callable, file: TextIO):
         if default is inspect.Parameter.empty:
             default = "_required_"
         else:
-            default = f"`{default}`"
+            default = f"`{repr(default)}`"
         print(f"| {name} | {typ} | {desc} | {default} |", file=file)
 
     print("\n", file=file)
@@ -117,10 +117,12 @@ def func_api(func: Callable, file: TextIO):
     rt = f"`{rt}`"
     desc = _parse_return_description(func)
     print(f"| {rt} | {desc} |", file=file)
+    print("\n\n", file=file)
 
 
 if __name__ == "__main__":
     with open("docs/api/functions.md", "w") as f:
         print("# Functions\n", file=f)
         func_api(start, f)
+        func_api(parse, f)
         func_api(register, f)