Add documentation links to CLI Commands (#130)

This will make it so our RTD that are generated either automatically via
CLI lib or through our custom docs will be included in the commands.

We need only make sure the root command matches the file name

i.e. `cwms-cli blob` matches `blob.rst` in the docs

Looks like this:
```bash
cwms-cli 
```
<img width="868" height="92" alt="image"
src="https://github.com/user-attachments/assets/246c9885-63cc-44b6-8aaa-48695fb0e5c9"
/>

and

```bash
cwms-cli usgs
```

<img width="885" height="114" alt="image"
src="https://github.com/user-attachments/assets/4b5dab9f-0d36-4201-8a4c-25c8dd961d97"
/>

---------

Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: krowvin <23619282+krowvin@users.noreply.github.com>

Author: krowvin

cwmscli/utils/click_help.py

@@ -1,12 +1,15 @@
 from __future__ import annotations
 
 import sys
+from typing import Optional
 
 import click
 
 from cwmscli.utils import colors
 from cwmscli.utils.version import get_cwms_cli_version
 
+DOCS_BASE_URL = "https://cwms-cli.readthedocs.io/en/latest"
+
 
 def _render_version_line(ctx: click.Context) -> str:
     # Match existing CLI color behavior: disable color for non-TTY, --no-color, or --log-file.
@@ -20,7 +23,41 @@ def _render_version_line(ctx: click.Context) -> str:
     return f"Version: {colors.c(get_cwms_cli_version(), 'cyan', bright=True)}"
 
 
-def _inject_version_line(help_text: str, ctx: click.Context) -> str:
+def _docs_url_for_context(ctx: click.Context) -> Optional[str]:
+    # Show docs links only on command root pages:
+    # - cwms-cli --help (depth 1)
+    # - cwms-cli <top-level-command> --help (depth 2)
+    depth = 0
+    cur = ctx
+    while cur is not None:
+        depth += 1
+        cur = cur.parent
+
+    if depth == 1:
+        return f"{DOCS_BASE_URL}/cli.html"
+    if depth != 2:
+        return None
+
+    command = (ctx.info_name or getattr(ctx.command, "name", None) or "").strip()
+    page_map = {
+        "blob": "blob",
+    }
+    # Link to dedicated pages that are created in \docs
+    if command in page_map:
+        return f"{DOCS_BASE_URL}/cli/{page_map[command]}.html"
+
+    # Fallback to the root CLI page with command anchor.
+    return f"{DOCS_BASE_URL}/cli.html#cwms-cli-{command}"
+
+
+def _render_docs_line(ctx: click.Context) -> Optional[str]:
+    docs_url = _docs_url_for_context(ctx)
+    if docs_url is None:
+        return None
+    return f"Docs: {colors.c(docs_url, 'blue', bright=True)}"
+
+
+def _inject_help_header(help_text: str, ctx: click.Context) -> str:
     lines = help_text.splitlines()
     if not lines:
         return help_text
@@ -30,24 +67,29 @@ def _inject_version_line(help_text: str, ctx: click.Context) -> str:
         return help_text
 
     version_line = _render_version_line(ctx)
+    docs_line = _render_docs_line(ctx)
     if lines[0].startswith("Usage:"):
         lines.insert(1, version_line)
+        if docs_line is not None:
+            lines.insert(2, docs_line)
     else:
         lines.insert(0, version_line)
+        if docs_line is not None:
+            lines.insert(1, docs_line)
     return "\n".join(lines)
 
 
 def _wrap_get_help(command: click.Command) -> None:
     original_get_help = command.get_help
 
-    def get_help_with_version(ctx: click.Context) -> str:
-        return _inject_version_line(original_get_help(ctx), ctx)
+    def get_help_with_header(ctx: click.Context) -> str:
+        return _inject_help_header(original_get_help(ctx), ctx)
 
-    command.get_help = get_help_with_version  # type: ignore[method-assign]
+    command.get_help = get_help_with_header  # type: ignore[method-assign]
 
 
 def add_version_to_help_tree(command: click.Command) -> None:
-    """Patch a command tree so every help output shows the CLI version."""
+    """Patch a command tree so every help output shows the CLI version and docs link."""
     stack = [command]
     seen: set[int] = set()
 

tests/cli/test_all_commands_help.py

@@ -2,6 +2,7 @@
 from click.testing import CliRunner
 
 from cwmscli.__main__ import cli
+from cwmscli.utils.click_help import DOCS_BASE_URL
 from cwmscli.utils.version import get_cwms_cli_version
 
 ## Expectations
@@ -37,6 +38,7 @@ def test_root_help(runner):
     assert result.exit_code == 0
     assert "Usage:" in result.output
     assert f"Version: {get_cwms_cli_version()}" in result.output
+    assert f"Docs: {DOCS_BASE_URL}/cli.html" in result.output
 
 
 def test_root_version_flag(runner):
@@ -62,3 +64,13 @@ def test_every_command_has_help(runner, path, command):
     assert result.exit_code == 0, f"Failed on: {' '.join(args)}"
     assert "Usage:" in result.output
     assert f"Version: {get_cwms_cli_version()}" in result.output
+    if len(path) == 1:
+        page_map = {
+            "blob": f"{DOCS_BASE_URL}/cli/blob.html",
+        }
+        expected_docs = page_map.get(
+            path[0], f"{DOCS_BASE_URL}/cli.html#cwms-cli-{path[0]}"
+        )
+        assert f"Docs: {expected_docs}" in result.output
+    else:
+        assert "Docs:" not in result.output