Add docs on the main function, argv and return codes

docs/mkdocs.yml

@@ -49,6 +49,8 @@ markdown_extensions:
 nav:
   - Home: index.md
   - contributing.md
+  - Language Features:
+    - howto/main_function.md
   - API Reference:
     - api_reference/python_builtins.md
   - Unsorted notes:

docs/src/howto/main_function.md

@@ -0,0 +1,53 @@
+title: The Main Function
+---
+
+All SPy programs must have a `main` function. The main function is the entry point of the program, and it is where the execution of the program begins.
+
+```py
+def main() -> None:
+    print("Hello world")
+```
+
+Not every `.spy` module needs a main function, but the module invoked by, e.g. `spy execute foo.spy` must contain a main function.
+
+## Return Codes
+
+The `main` function may be typed to return an `int` (`i32`). If so, the return value of the main function will be the return value of the program:
+
+```py
+#retcode.spy
+def main() -> int
+    return 123
+```
+```
+$ uv run spy retcode.spy
+$ echo $?
+123
+```
+
+
+## Passed Arguments (Interpretter Only)
+
+If the `main` function accepts a list of strings as an argument, the SPy program will accept arguments from the command line, both when running in interpretted
+
+```py
+#args.spy
+def main(args: list[str]) -> None:
+    print(args[1])
+```
+```
+$ uv run spy args.spy 999
+999
+```
+
+As with CPython, args[0] is the name of the string passed to the uv runtime:
+
+```py
+#argname.spy
+def main(args: list[str]) -> None:
+    print(args[0])
+```
+```
+$ uv run spy argname.spy
+foo.spy
+```