From: Ville Ojamo <14869000+bluikko@users.noreply.github.com>
Date: Mon, 28 Apr 2025 09:19:22 +0000 (+0700)
Subject: doc/radosgw: Promptify CLI commands and fix formatting in layout.rst
X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=26b0a522ed2323438bd172c6aa0b3490c21b80f8;p=ceph.git

doc/radosgw: Promptify CLI commands and fix formatting in layout.rst

Move two example CLI command blocks to use a bash prompt
block with the correct privileged prompt instead of
hardcoded unprivileged prompt.

Don't use the directory "bin/" in command "bin/radosgw-admin"
especially when the next commands also don't use it.

Fix 2 instances of double-backtick missing the second
backtick that caused the rendered doc to be jumbled.

Do not use _emphasis_ that renders as underscores, instead
use RST syntax for italic for the word.

Signed-off-by: Ville Ojamo <14869000+bluikko@users.noreply.github.com>
(cherry picked from commit 6783245e98be4bd83be754fa39353d268e25b896)
---

diff --git a/doc/radosgw/layout.rst b/doc/radosgw/layout.rst
index f7ef71c01b0eb..523e448a260f3 100644
--- a/doc/radosgw/layout.rst
+++ b/doc/radosgw/layout.rst
@@ -25,17 +25,37 @@ metadata, bucket indexes, and (payload) data.
 Metadata
 ^^^^^^^^
 
-We have three 'sections' of metadata: 'user', 'bucket', and 'bucket.instance'.
-You can use the following commands to inspect metadata entries: ::
+RGW stores multiple types of metadata.  The list of types can be shown
+with the below command. The types as of 2025 April are shown below:
 
-    $ radosgw-admin metadata list
-    $ radosgw-admin metadata list bucket
-    $ radosgw-admin metadata list bucket.instance
-    $ radosgw-admin metadata list user
+.. prompt:: bash #
 
-    $ radosgw-admin metadata get bucket:<bucket>
-    $ radosgw-admin metadata get bucket.instance:<bucket>:<bucket_id>
-    $ radosgw-admin metadata get user:<user>   # get or set
+   radosgw-admin metadata list
+
+::
+
+    [
+        "account",
+        "bucket",
+        "bucket.instance",
+        "group",
+        "otp",
+        "roles",
+        "topic",
+        "user"
+    ]
+
+Use commands of the following forms to inspect metadata entries:
+
+.. prompt:: bash #
+
+   radosgw-admin metadata list
+   radosgw-admin metadata list bucket
+   radosgw-admin metadata list bucket.instance
+   radosgw-admin metadata list user
+   radosgw-admin metadata get bucket:<bucket>
+   radosgw-admin metadata get bucket.instance:<bucket>:<bucket_id>
+   radosgw-admin metadata get user:<user>   # get or set
     
 Some variables have been used in above commands, they are:
 
@@ -104,7 +124,7 @@ is controlled by a 'policy' setting.[3]
 An RGW object may comprise multiple RADOS objects, the first of which
 is the ``HEAD`` that contains metadata including manifest, ACLs, content type,
 ETag, and user-defined metadata. The metadata is stored in xattrs.
-The ``HEAD` object may also inline up to :confval:`rgw_max_chunk_size` of object data, for efficiency
+The ``HEAD`` object may also inline up to :confval:`rgw_max_chunk_size` of object data, for efficiency
 and atomicity.  This enables a convenenient tiering strategy:  index pools
 are necessarily replicated (cannot be EC) and should be placed on fast SSD
 OSDs.  With a mix of small/hot RGW objects and larger, warm/cold RGW
@@ -179,7 +199,7 @@ Known pools:
       testcont
 
   namespace: ``users.uid``
-    Contains _both_ per-user information (RGWUserInfo) in "<user>" objects
+    Contains *both* per-user information (RGWUserInfo) in "<user>" objects
     and per-user lists of buckets in omaps of "<user>.buckets" objects.
     The "<user>" may contain the tenant if non-empty, for example::
 
@@ -208,7 +228,7 @@ Known pools:
   example: ``default.7593.4__shadow_.488urDFerTYXavx4yAd-Op8mxehnvTI_1``
   <marker>_<key>
 
-An example of a marker would be ``default.16004.1`` or `default.7593.4``.
+An example of a marker would be ``default.16004.1`` or ``default.7593.4``.
 The current format is ``<zone>.<instance_id>.<bucket_id>``. But once
 generated, a marker is not parsed again, so its format may change
 freely in the future.