Repository: pantsbuild/pants

Issue:
run_shell_command - documentation page is confusing
**Describe the bug**
The [documentation page](https://www.pantsbuild.org/docs/reference-run_shell_command) for "run_shell_command" is a bit confusing.
- The description for the `execution_dependencies` field and the `runnable_dependencies` field starts the same way.
- The description for these fields refers to `output_dependencies`, which is not there.
- There is a typo under `runnable_dependencies` - missing backtick in the last line.

**Pants version**
2.16

**Additional info**
I apologize if this is not the way to report issues in the documentation.



Discussion:
Thanks for reporting. This is the right place for doc issues!

Resolving patch:
diff --git a/src/python/pants/backend/adhoc/target_types.py b/src/python/pants/backend/adhoc/target_types.py
--- a/src/python/pants/backend/adhoc/target_types.py
+++ b/src/python/pants/backend/adhoc/target_types.py
@@ -82,9 +82,12 @@ class AdhocToolOutputDependenciesField(AdhocToolDependenciesField):
     alias: ClassVar[str] = "output_dependencies"
 
     help = help_text(
-        lambda: """
+        lambda: f"""
         Any dependencies that need to be present (as transitive dependencies) whenever the outputs
         of this target are consumed (including as dependencies).
+
+        See also `{AdhocToolExecutionDependenciesField.alias}` and
+        `{AdhocToolRunnableDependenciesField.alias}`.
         """
     )
 
@@ -106,6 +109,9 @@ class AdhocToolExecutionDependenciesField(SpecialCasedDependencies):
 
         If this field is specified, dependencies from `{AdhocToolOutputDependenciesField.alias}`
         will not be added to the execution sandbox.
+
+        See also `{AdhocToolOutputDependenciesField.alias}` and
+        `{AdhocToolRunnableDependenciesField.alias}`.
         """
     )
 
@@ -117,7 +123,7 @@ class AdhocToolRunnableDependenciesField(SpecialCasedDependencies):
 
     help = help_text(
         lambda: f"""
-        The execution dependencies for this command.
+        The runnable dependencies for this command.
 
         Dependencies specified here are those required to exist on the `PATH` to make the command
         complete successfully (interpreters specified in a `#!` command, etc). Note that these
diff --git a/src/python/pants/backend/shell/target_types.py b/src/python/pants/backend/shell/target_types.py
--- a/src/python/pants/backend/shell/target_types.py
+++ b/src/python/pants/backend/shell/target_types.py
@@ -293,10 +293,38 @@ class ShellCommandExecutionDependenciesField(AdhocToolExecutionDependenciesField
     pass
 
 
+class RunShellCommandExecutionDependenciesField(ShellCommandExecutionDependenciesField):
+    help = help_text(
+        lambda: f"""
+        The execution dependencies for this command.
+
+        Dependencies specified here are those required to make the command complete successfully
+        (e.g. file inputs, packages compiled from other targets, etc), but NOT required to make
+        the outputs of the command useful.
+
+        See also `{RunShellCommandRunnableDependenciesField.alias}`.
+        """
+    )
+
+
 class ShellCommandRunnableDependenciesField(AdhocToolRunnableDependenciesField):
     pass
 
 
+class RunShellCommandRunnableDependenciesField(ShellCommandRunnableDependenciesField):
+    help = help_text(
+        lambda: f"""
+        The runnable dependencies for this command.
+
+        Dependencies specified here are those required to exist on the `PATH` to make the command
+        complete successfully (interpreters specified in a `#!` command, etc). Note that these
+        dependencies will be made available on the `PATH` with the name of the target.
+
+        See also `{RunShellCommandExecutionDependenciesField.alias}`.
+        """
+    )
+
+
 class ShellCommandSourcesField(MultipleSourcesField):
     # We solely register this field for codegen to work.
     alias = "_sources"
@@ -400,8 +428,8 @@ class ShellCommandRunTarget(Target):
     alias = "run_shell_command"
     core_fields = (
         *COMMON_TARGET_FIELDS,
-        ShellCommandExecutionDependenciesField,
-        ShellCommandRunnableDependenciesField,
+        RunShellCommandExecutionDependenciesField,
+        RunShellCommandRunnableDependenciesField,
         ShellCommandCommandField,
         RunShellCommandWorkdirField,
     )


Test patch: