Improve @py macro documentation (#712)

* Improve @py macro documentation

* docstring edits

Author: cjdoris

src/PyMacro/PyMacro.jl

@@ -860,18 +860,59 @@ end
 """
     @py expr
 
-Evaluate the given expression using Pythonic semantics.
-
-For example:
-- `f(x, y)` is translated to `pycall(f, x, y)`
-- `x + y` is translated to `pyadd(x, y)`
-- `x === y` is translated to `pyis(x, y)` (`x is y` in Python)
-- `x.foo` is translated to `pygetattr(x, "foo")`
-- `import x: f as g` is translated to `g = pyimport("x" => "f")` (`from x import f as g` in Python)
-
-Compound statements such as `begin`, `if`, `while` and `for` are supported.
-
-See the online documentation for more details.
+Evaluate `expr` using Python-like syntax and semantics and return the
+resulting [`Py`](@ref) object.
+
+Supported syntax includes:
+
+* **Literals and names:** Numeric and string literals, `None`, `True`, `False`,
+  containers (`(…)`, `[…]`, `{…}`, `{key:value, …}`) and special
+  placeholders such as `__file__` and `__line__`.
+* **Calls and operators:** Function calls are translated to `pycall`, unary
+  and binary operators are forwarded to the corresponding `py*` helper
+  (e.g. `x + y` → `pyadd(x, y)`, `x === y` → `pyis(x, y)`), and chained
+  arithmetic or comparison expressions behave like their Python equivalents.
+* **Attribute access and indexing:** `obj.attr`, `obj[key]`, and slice syntax
+  (`obj[start:stop:step]`) map to `pygetattr`, `pygetitem`, and `pyslice`.
+* **Statements:** Assignments, `@del` deletions, `if`/`elseif`/`else`, `while`, `for`,
+  short-circuit boolean logic (`&&`/`||`). Import statements
+  (`import pkg`, `import pkg as alias`, `import pkg: attr as alias`) are
+  also supported.
+* **Interop helpers:** Use `@jl expr` to splice the result of a Julia
+  expression into the Python evaluation. The auxiliary macros `@compile`,
+  `@eval`, and `@exec` work like `compile`/`eval`/`exec` in Python but compile
+  the code argument once and reuse it for speed.
+
+Names that match Python builtins are resolved through [`pybuiltins`](@ref); other
+identifiers are captured from the surrounding Julia scope.
+
+# Examples
+
+```julia
+julia> @py begin
+           import math: sqrt
+           sqrt(9)
+       end
+Py(3.0)
+
+julia> factor = 10
+julia> @py begin
+           data = [1, 2, @jl factor]
+           total = 0
+           for value in data
+               total = total + value
+           end
+           total
+       end
+Py(13)
+
+julia> @py begin
+           info = {"x": 1, "y": 2}
+           @del info["x"]
+           info
+       end
+Py({'y': 2})
+```
 
 !!! warning
     This macro is experimental. It may be modified or removed in a future release.