docs: recommend alternatives to podman inspect

podman inspect is problematic because there can be naming clashes. Also,
it only inspects a couple of types of objects and the docs for it didn't
help discover that several more types could be inspected as well.

To address both concerns, we deprecate `podman inspect` and update the
docs to point to to the recommend alternatives.

Issue: #6756
Signed-off-by: Mark Stosberg <mark@rideamigos.com>

cmd/podman/inspect.go

@@ -8,12 +8,22 @@ import (
 )
 
 var (
+	inspectDescription = `Displays the low-level information on an object identified by name or ID.
+  For more inspection options, see:
+
+      podman container inspect
+      podman image inspect
+      podman network inspect
+      podman pod inspect
+      podman volume inspect`
+
 	// Command: podman _inspect_ Object_ID
 	inspectCmd = &cobra.Command{
-		Use:   "inspect [flags] {CONTAINER_ID | IMAGE_ID} [...]",
-		Short: "Display the configuration of object denoted by ID",
-		Long:  "Displays the low-level information on an object identified by name or ID",
-		RunE:  inspectExec,
+		Use:              "inspect [flags] {CONTAINER_ID | IMAGE_ID} [...]",
+		Short:            "Display the configuration of object denoted by ID",
+		RunE:             inspectExec,
+		Long:             inspectDescription,
+		TraverseChildren: true,
 		Example: `podman inspect fedora
   podman inspect --type image fedora
   podman inspect CtrID ImgID

docs/source/markdown/podman-inspect.1.md

@@ -6,15 +6,21 @@ podman\-inspect - Display a container or image's configuration
 ## SYNOPSIS
 **podman inspect** [*options*] *name* [...]
 
-**podman image inspect** [*options*] *image*
-
-**podman container inspect** [*options*] *container*
-
 ## DESCRIPTION
+
 This displays the low-level information on containers and images identified by name or ID. By default, this will render
 all results in a JSON array. If the container and image have the same name, this will return container JSON for
 unspecified type. If a format is specified, the given template will be executed for each result.
 
+For more inspection options, see:
+
+      podman container inspect
+      podman image inspect
+      podman network inspect
+      podman pod inspect
+      podman volume inspect
+
+
 ## OPTIONS
 
 **--type**, **-t**=*type*