refactor: reorder and document repo view, pr create

frg/cli.py

@@ -15,34 +15,67 @@ 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):
-    forgejo_browser.create_pull_request_via_web(
-        head=ctx.git.current_branch,
-        host=ctx.git.host,
-        repo=ctx.git.repo_name,
-        owner=ctx.git.repo_author,
-    )
+    """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,
+            repo=ctx.git.repo_name,
+            owner=ctx.git.repo_author,
+        )
 
 
 @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):
-    forgejo_browser.view_repository_via_web(
-        host=ctx.git.host, repo=ctx.git.repo_name, owner=ctx.git.repo_author
-    )
+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():