refactor: reorder and document repo view, pr create

frg/cli.py

@@ -15,14 +15,35 @@ class CliContext(pydantic.BaseModel):
 @click.group()
 @click.pass_context
 def cli(ctx):
+    """
+    A command-line tool to interact with different kinds of code forges.
+    """
+
     config = get_configuration()
     git_context = get_git_context(domain_aliases=config.domain_aliases)
     ctx.obj = CliContext(git=git_context, config=config)
 
 
-@cli.command()
+@cli.group()
 @click.pass_obj
 def pr(ctx):
+    """Interacts with pull requests."""
+    pass
+
+
+@pr.command(name="create")
+@click.option(
+    "-w",
+    "--web",
+    type=bool,
+    is_flag=True,
+    help="Opens the pull-request page in the default browser.",
+)
+@click.pass_obj
+def create_pr(ctx, web: bool):
+    """Interacts with pull requests."""
+
+    if web:
         forgejo_browser.create_pull_request_via_web(
             head=ctx.git.current_branch,
             host=ctx.git.host,
@@ -34,15 +55,27 @@ def pr(ctx):
 @cli.group()
 @click.pass_obj
 def repo(ctx):
+    """Interacts with repositories"""
     pass
 
 
-@repo.command()
+@repo.command(name="view")
+@click.option(
+    "-w",
+    "--web",
+    type=bool,
+    is_flag=True,
+    help="Opens the repository page in the default browser.",
+)
 @click.pass_obj
-def view(ctx):
+def view_repo(ctx, web: bool):
+    """View the current repository."""
+    if web:
         forgejo_browser.view_repository_via_web(
             host=ctx.git.host, repo=ctx.git.repo_name, owner=ctx.git.repo_author
         )
+    else:
+        raise NotImplementedError("--web is the only mode supported.")
 
 
 def main():