docs(cli): Add CLI documentation page with argparse output

- Add create_parser() function to g module for documentation and --version
- Create docs/cli/index.md using sphinx-argparse directive
- Add cli/index to docs toctree
- Support --version/-V flag in CLI

Author: tony

docs/cli/index.md

@@ -0,0 +1,55 @@
+(cli)=
+
+# CLI
+
+g is a minimal CLI wrapper that proxies to your current directory's VCS command.
+
+## How it works
+
+When you run `g`, it:
+
+1. Walks up from your current directory looking for `.git`, `.svn`, or `.hg`
+2. Invokes the corresponding VCS (`git`, `svn`, or `hg`) with your arguments
+3. Exits after the command completes
+
+## Usage
+
+```console
+$ g status
+```
+
+Is equivalent to:
+
+```console
+$ git status  # if in a git repo
+$ svn status  # if in an svn repo
+$ hg status   # if in an hg repo
+```
+
+(cli-main)=
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: g
+    :func: create_parser
+    :prog: g
+```
+
+## Examples
+
+```console
+$ g status
+$ g commit -m "Fix bug"
+$ g log --oneline -10
+$ g diff HEAD~1
+```
+
+## Supported VCS
+
+| Directory marker | VCS command |
+|------------------|-------------|
+| `.git`           | `git`       |
+| `.svn`           | `svn`       |
+| `.hg`            | `hg`        |

docs/index.md

@@ -8,6 +8,7 @@
 :hidden:
 
 quickstart
+cli/index
 ```
 
 ```{toctree}

src/g/__init__.py

@@ -3,7 +3,7 @@
 
 from __future__ import annotations
 
-import io
+import argparse
 import logging
 import os
 import pathlib
@@ -12,7 +12,9 @@
 import typing as t
 from os import PathLike
 
-__all__ = ["DEFAULT", "run", "sys", "vcspath_registry"]
+from g.__about__ import __version__
+
+__all__ = ["DEFAULT", "create_parser", "run", "sys", "vcspath_registry"]
 
 vcspath_registry = {".git": "git", ".svn": "svn", ".hg": "hg"}
 
@@ -28,6 +30,49 @@ def find_repo_type(path: pathlib.Path | str) -> str | None:
     return None
 
 
+def create_parser() -> argparse.ArgumentParser:
+    """Create argument parser for g CLI.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for the g command.
+
+    Examples
+    --------
+    >>> parser = create_parser()
+    >>> parser.prog
+    'g'
+
+    >>> args = parser.parse_args(['status'])
+    >>> args.vcs_args
+    ['status']
+
+    >>> args = parser.parse_args(['commit', '-m', 'message'])
+    >>> args.vcs_args
+    ['commit', '-m', 'message']
+    """
+    parser = argparse.ArgumentParser(
+        prog="g",
+        description="CLI alias for your current directory's VCS command (git, svn, hg).",
+        epilog="All arguments are passed directly to the detected VCS.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--version",
+        "-V",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "vcs_args",
+        nargs=argparse.REMAINDER,
+        metavar="...",
+        help="Arguments passed to the detected VCS (git, svn, or hg)",
+    )
+    return parser
+
+
 DEFAULT = object()
 
 
@@ -47,19 +92,25 @@ def run(
         returned, it would print *<Popen: returncode: 1 args: ['git']>* after command.
     """
     # Interpret default kwargs lazily for mockability of argv
-    if cmd is DEFAULT:
-        cmd = find_repo_type(pathlib.Path.cwd())
     if cmd_args is DEFAULT:
         cmd_args = sys.argv[1:]
 
+    # Handle --version/-V before VCS detection
+    assert isinstance(cmd_args, (tuple, list))
+    if cmd_args and cmd_args[0] in ("--version", "-V"):
+        parser = create_parser()
+        parser.parse_args(["--version"])  # Will print version and exit
+
+    if cmd is DEFAULT:
+        cmd = find_repo_type(pathlib.Path.cwd())
+
     logging.basicConfig(level=logging.INFO, format="%(message)s")
 
     if cmd is None:
         msg = "No VCS found in current directory."
         log.info(msg)
         return None
 
-    assert isinstance(cmd_args, (tuple, list))
     assert isinstance(cmd, (str, bytes, pathlib.Path))
 
     proc = subprocess.Popen([cmd, *cmd_args], **kwargs)