Repository: ceph/ceph
Pull request #62763: doc/radosgw: Promptify CLI, cosmetic fixes
Author: login: bluikko
Labels: name: documentation
Created: 2025-04-10T10:47:28Z | Merged: 2025-04-17T02:55:28Z

Use the more modern prompt block for CLI commands and use right one $ vs #.

Fix indentation on JSON example outputs and some CLI command switches.

Add some arguably missing comma in JSON example output.

Add a full stop at the end of a one-sentence paragraph. Remove extra comma mid-sentence in another.

Fix missing backslashes or typo at end of multiline commands.

Lines under section headings as long as heading text.

Fix hyperlinks. Fix list items prefixed with `-` insted of `*`. Format configuration syntax in the middle of text as ``code``.

Fix typo "PI" to "API" and remove extra space between it and the following full stop. Remove colons at the end of section headers in a few places. Use Title Case in section titles consistently with short words lowercase.

Don't try to create code blocks with triple backtick as it won't work, use double colon (in the end of preceding text paragraph as other files do, could be just `::` on its own line too I suppose).

Possibly controversial: don't add whitespace before and after main title section header text. Few were like this and changed for consistency with other such title lines.

Possibly controversial: don't indent line continuation backslashes, leave only 1 space before them.





<!--
  - Please give your pull request a title like

      [component]: [short description]

  - Please use this format for each git commit message:

      [component]: [short description]

      [A longer multiline description]

      Fixes: [ticket URL on tracker.ceph.com, create one if necessary]
      Signed-off-by: [Your Name] <[your email]>

    For examples, use "git log".
-->

## Contribution Guidelines
- To sign and title your commits, please refer to [Submitting Patches to Ceph](https://github.com/ceph/ceph/blob/main/SubmittingPatches.rst).

- If you are submitting a fix for a stable branch (e.g. "quincy"), please refer to [Submitting Patches to Ceph - Backports](https://github.com/ceph/ceph/blob/master/SubmittingPatches-backports.rst) for the proper workflow.

- When filling out the below checklist, you may click boxes directly in the GitHub web UI.  When entering or editing the entire PR message in the GitHub web UI editor, you may also select a checklist item by adding an `x` between the brackets: `[x]`.  Spaces and capitalization matter when checking off items this way.

## Checklist
- Tracker (select at least one)
  - [ ] References tracker ticket
  - [ ] Very recent bug; references commit where it was introduced
  - [ ] New feature (ticket optional)
  - [x] Doc update (no ticket needed)
  - [ ] Code cleanup (no ticket needed)
- Component impact
  - [ ] Affects [Dashboard](https://tracker.ceph.com/projects/dashboard/issues/new), opened tracker ticket
  - [ ] Affects [Orchestrator](https://tracker.ceph.com/projects/orchestrator/issues/new), opened tracker ticket
  - [x] No impact that needs to be tracked
- Documentation (select at least one)
  - [x] Updates relevant documentation
  - [ ] No doc update is appropriate
- Tests (select at least one)
  - [ ] Includes [unit test(s)](https://docs.ceph.com/en/latest/dev/developer_guide/tests-unit-tests/)
  - [ ] Includes [integration test(s)](https://docs.ceph.com/en/latest/dev/developer_guide/testing_integration_tests/)
  - [ ] Includes bug reproducer
  - [x] No tests

<details>
<summary>Show available Jenkins commands</summary>

- `jenkins test classic perf` [Jenkins Job](https://jenkins.ceph.com/view/all/job/ceph-perf-classic/) | [Jenkins Job Definition](https://github.com/ceph/ceph-build/blob/main/ceph-perf-pull-requests/config/definitions/ceph-perf-pull-requests.yml)
- `jenkins test crimson perf` [Jenkins Job](https://jenkins.ceph.com/view/all/job/ceph-perf-crimson/) | [Jenkins Job Definition](https://github.com/ceph/ceph-build/blob/main/ceph-perf-pull-requests/config/definitions/ceph-perf-pull-requests.yml)
- `jenkins test signed` [Jenkins Job](https://jenkins.ceph.com/job/ceph-pr-commits/) | [Jenkins Job Definition](https://github.com/ceph/ceph-build/blob/main/ceph-pr-commits/config/definitions/ceph-pr-commits.yml)
- `jenkins test make check` [Jenkins Job](https://jenkins.ceph.com/job/ceph-pull-requests/) | [Jenkins Job Definition](https://github.com/ceph/ceph-build/blob/main/ceph-pull-requests/config/definitions/ceph-pull-requests.yml)
- `jenkins test make check arm64` [Jenkins Job](https://jenkins.ceph.com/job/ceph-pull-requests-arm64/) | [Jenkins Job Definition](https://github.com/ceph/ceph-build/blob/main/ceph-pull-requests-arm64/config/definitions/ceph-pull-requests-arm64.yml)
- `jenkins test submodules` [Jenkins Job](https://jenkins.ceph.com/view/all/job/ceph-pr-submodules/) | [Jenkins Job Definition](https://github.com/ceph/ceph-build/blob/main/ceph-pr-submodules/config/definitions/ceph-pr-commits.yml)
- `jenkins test dashboard` [Jenkins Job](https://jenkins.ceph.com/view/all/job/ceph-dashboard-pull-requests/) | [Jenkins Job Definition](https://github.com/ceph/ceph-build/blob/main/ceph-dashboard-pull-requests/config/definitions/ceph-dashboard-pull-requests.yml)
- `jenkins test dashboard cephadm` [Jenkins Job](https://jenkins.ceph.com/view/all/job/ceph-dashboard-cephadm-e2e/) | [Jenkins Job Definition](https://github.com/ceph/ceph-build/blob/main/ceph-dashboard-cephadm-e2e/config/definitions/ceph-dashboard-cephadm-e2e.yml)
- `jenkins test api` [Jenkins Job](https://jenkins.ceph.com/view/all/job/ceph-api/) | [Jenkins Job Definition](https://github.com/ceph/ceph-build/blob/main/ceph-pr-api/config/definitions/ceph-pr-api.yml)
- `jenkins test docs` [ReadTheDocs](https://readthedocs.org/projects/ceph/) | [Github Workflow Definition](https://github.com/ceph/ceph/blob/main/.readthedocs.yml)
- `jenkins test ceph-volume all` [Jenkins Jobs](https://jenkins.ceph.com/view/ceph-volume%20PR/) | [Jenkins Jobs Definition](https://github.com/ceph/ceph-build/blob/main/ceph-volume-cephadm-prs/config/definitions/ceph-volume-pr.yml)
- `jenkins test windows` [Jenkins Job](https://jenkins.ceph.com/job/ceph-windows-pull-requests/) | [Jenkins Job Definition](https://github.com/ceph/ceph-build/blob/main/ceph-windows-pull-requests/config/definitions/ceph-windows-pull-requests.yml)
- `jenkins test rook e2e` [Jenkins Job](https://jenkins.ceph.com/view/all/job/ceph-orchestrator-rook-e2e/) | [Jenkins Job Definition](https://github.com/ceph/ceph-build/blob/main/ceph-rook-e2e/config/definitions/ceph-orchestrator-rook-e2e.yml)
</details>



Diff:
diff --git a/doc/radosgw/archive-sync-module.rst b/doc/radosgw/archive-sync-module.rst
index f9779f23ceba1..be6f571e428f4 100644
--- a/doc/radosgw/archive-sync-module.rst
+++ b/doc/radosgw/archive-sync-module.rst
@@ -30,11 +30,13 @@ See `Multisite Configuration`_ for multisite configuration instructions. The
 archive sync module requires the creation of a new zone. The zone tier type needs
 to be defined as ``archive``:
 
-::
+.. prompt:: bash #
+
+   radosgw-admin zone create --rgw-zonegroup={zone-group-name} \
+                               --rgw-zone={zone-name} \
+                               --endpoints={http://fqdn}[,{http://fqdn}] \
+                               --tier-type=archive
+
 
-    # radosgw-admin zone create --rgw-zonegroup={zone-group-name} \
-                                --rgw-zone={zone-name} \
-                                --endpoints={http://fqdn}[,{http://fqdn}]
-                                --tier-type=archive
 
 .. _Multisite Configuration: ../multisite
diff --git a/doc/radosgw/cloud-restore.rst b/doc/radosgw/cloud-restore.rst
index 701439d950fce..3d7114081c0f6 100644
--- a/doc/radosgw/cloud-restore.rst
+++ b/doc/radosgw/cloud-restore.rst
@@ -1,6 +1,6 @@
-===============
- Cloud Restore 
-===============
+=============
+Cloud Restore
+=============
 
 The :doc:`cloud-transition>` feature makes it possible to transition objects to a remote
 cloud service. The ``cloud-restore`` feature described below enables restoration
@@ -12,23 +12,22 @@ S3-compatible cloud services. In order to faciliate this,
 the ``retain_head_object`` option should be set to ``true``
 in the ``tier-config`` when configuring the storage class.
 
-Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`
-PI . The restored copies will be retained within RGW only for the number
+Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`_
+API. The restored copies will be retained within RGW only for the number
 of ``days`` specified. However if ``days`` is not provided, the restored copies
 are considered permanent and will be treated as regular objects.
 In addition, by enabling the ``allow_read_through`` option,
-the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`
+the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`_
 API can be used to restore the object temporarily.
 
 
 Cloud Storage Class Tier Configuration
 --------------------------------------
 
-The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`
+The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`_
 of the cloud storage class configured for data transition is used to restore
-objects as well:
+objects as well::
 
-```
     {
       "access_key": <access>,
       "secret": <secret>,`
@@ -44,7 +43,6 @@ objects as well:
       "multipart_min_part_size": {part_size},
       "retain_head_object": <true | false>
     }
-```
 
 The below options have been added to the tier configuration to facilitate object restoration.
 
@@ -53,7 +51,7 @@ The below options have been added to the tier configuration to facilitate object
 The storage class to which object data is to be restored. Default value is ``STANDARD``.
 
 
-read-through specific Configurables:
+Read-through Specific Configurables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * ``allow_read_through`` (``true`` | ``false``)
@@ -67,20 +65,21 @@ Default value is 1 day.
 
 For example:
 
-```
-    # radosgw-admin zonegroup placement modify --rgw-zonegroup default \
-                                               --placement-id default-placement \
-                                               --storage-class CLOUDTIER \
-                                               --tier-config=endpoint=http://XX.XX.XX.XX:YY,\
-                                               access_key=<access_key>,secret=<secret>, \
-                                               retain_head_object=true, \
-                                               restore_storage_class=COLDTIER, \
-                                               allow_read_through=true, \
-                                               read_through_restore_days=10
-```
+.. prompt:: bash #
 
+   radosgw-admin zonegroup placement modify --rgw-zonegroup default \
+                                              --placement-id default-placement \
+                                              --storage-class CLOUDTIER \
+                                              --tier-config=endpoint=http://XX.XX.XX.XX:YY,\
+                                              access_key=<access_key>,secret=<secret>, \
+                                              retain_head_object=true, \
+                                              restore_storage_class=COLDTIER, \
+                                              allow_read_through=true, \
+                                              read_through_restore_days=10
 
-S3 Glacier specific Configurables:
+
+
+S3 Glacier Specific Configurables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To restore objects archived in an S3 Glacier or Tape cloud storage class, the
@@ -101,26 +100,27 @@ pricing. Supported options are ``Standard`` and ``Expedited``.
 
 For example:
 
-```
-    # radosgw-admin zonegroup placement add --rgw-zonegroup=default \
-                                            --placement-id=default-placement \
-                                            --storage-class=CLOUDTIER-GLACIER --tier-type=cloud-s3-glacier
-
-    # radosgw-admin zonegroup placement modify --rgw-zonegroup default \
-                                               --placement-id default-placement \
-                                               --storage-class CLOUDTIER \
-                                               --tier-config=endpoint=http://XX.XX.XX.XX:YY,\
-                                               access_key=XXXXX,secret=YYYYY, \
-                                               retain_head_object=true, \
-                                               target_storage_class=Glacier, \
-                                               ............
-                                               ............
-                                               restore_storage_class=COLDTIER, \
-                                               glacier_restore_days=2, \
-                                               glacier_restore_tier_type=Expedited
-
-
-     [
+.. prompt:: bash #
+
+   radosgw-admin zonegroup placement add --rgw-zonegroup=default \
+                                           --placement-id=default-placement \
+                                           --storage-class=CLOUDTIER-GLACIER --tier-type=cloud-s3-glacier
+   radosgw-admin zonegroup placement modify --rgw-zonegroup default \
+                                              --placement-id default-placement \
+                                              --storage-class CLOUDTIER \
+                                              --tier-config=endpoint=http://XX.XX.XX.XX:YY,\
+                                              access_key=XXXXX,secret=YYYYY, \
+                                              retain_head_object=true, \
+                                              target_storage_class=Glacier, \
+                                              ............ \
+                                              ............ \
+                                              restore_storage_class=COLDTIER, \
+                                              glacier_restore_days=2, \
+                                              glacier_restore_tier_type=Expedited
+
+::
+
+    [
         {
             "key": "default-placement",
             "val": {
@@ -159,47 +159,47 @@ For example:
             }
         }
     ]
-```
 
 
-Examples of Restore Objects:
-----------------------------
+Examples of Restore Objects
+---------------------------
 
 Using the S3 RestoreObject CLI
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Th `S3 restore-object <https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html>`
+Th `S3 restore-object <https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html>`_
 CLI supports these options:
 
-```
-  $ aws s3api restore-object 
-            --bucket <value>
-            --key <value>
-            [--version-id <value>]
-            --restore-request (structure) {
-              Days=<integer>
-            }
-```
+.. prompt:: bash $
+
+   aws s3api restore-object --bucket <value> \
+                              --key <value> \
+                              [--version-id <value>] \
+                              --restore-request (structure) { \
+                                Days=<integer> \
+                              }
+
 
 Note: ``Days`` is optional and if not provided, the object is restored permanently.
 
 Example 1:
 
-```
-  $ aws s3api restore-object  --bucket bucket1 --key doc1.rtf 
-                              [--version-id 3sL4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo]
-                              --restore-request Days=10 
+.. prompt:: bash $
+
+   aws s3api restore-object --bucket bucket1 --key doc1.rtf \
+                              [--version-id 3sL4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo] \
+                              --restore-request Days=10 \
                               ....
-```
+
 
 This will restore the object ``doc1.rtf`` at an optional version,
 for the duration of 10 days.
 
 Example 2:
 
-```
-  $ aws s3api restore-object  --bucket bucket1 --key doc2.rtf --restore-request {} ....
-```
+.. prompt:: bash $
+
+   aws s3api restore-object --bucket bucket1 --key doc2.rtf --restore-request {} ....
 
 
 This will restore the object ``doc2.rtf`` permanently and it will be treated as regular object.
@@ -212,9 +212,10 @@ Ensure that the ``allow_read_through`` tier-config option is enabled.
 
 Example 3:
 
-```
-  $ aws s3api get-object  --bucket bucket1 --key doc3.rtf ....
-```
+.. prompt:: bash $
+
+   aws s3api get-object --bucket bucket1 --key doc3.rtf ....
+
 
 This will restore the object `doc3.rtf`` for ``read_through_restore_days`` days.
 
@@ -222,49 +223,51 @@ Note: The above CLI command may time out if object restoration takes too long.
 You can verify the restore status before reissuing the command.
 
 
-Verifying the restoration status
+Verifying the Restoration Status
 --------------------------------
 Verify the status of the restoration by issuing
-an `S3 HeadObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html#API_HeadObject_ResponseSyntax>`
+an `S3 HeadObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html#API_HeadObject_ResponseSyntax>`_
 request. The response includes the ``x-amz-restore`` header if object restoration
 is in progress or a copy of it is already restored.
 
 Example:
 
-```
-  $ aws s3api head-object --key doc1.rtf --bucket bucket1 ....
-```
+.. prompt:: bash $
+
+   aws s3api head-object --key doc1.rtf --bucket bucket1 ....
+
 
 The ``radosgw-admin`` CLI can be used to check restoration status and other
 details.
 
 Example:
 
-```  
- $ radosgw-admin object stat --bucket bucket1 --object doc1.rtf
-```
+.. prompt:: bash $
+
+   radosgw-admin object stat --bucket bucket1 --object doc1.rtf
+
 
 
 Restored Object Properties
 --------------------------
 
 Storage
-~~~~~~
+~~~~~~~
 Objects are restored to the storage class configured via ``restore_storage_class``
 in the tier-config. However, as
-per `<https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html>`
+per `<https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html>`_
 the storage class of restored objects should remain unchanged. Therefore, for
-temporary copies, the ```x-amz-storage-class``` will continue to reflect the
+temporary copies, the ``x-amz-storage-class`` will continue to reflect the
 original cloud-tier storage class.
 
 
 mtime
-~~~~
+~~~~~
 The ``mtime`` of the transitioned and restored objects should remain unchanged.
 
 
 Lifecycle
-~~~~~~~~
+~~~~~~~~~
 ``Temporary`` copies are not subject to transition to the cloud. However, as is the
 case with cloud-transitioned objects, they can be deleted via regular LC (Life Cycle)
 expiration rules or an external S3 ``delete`` request.
@@ -274,7 +277,7 @@ policies.
 
 
 Replication
-~~~~~~~~~~
+~~~~~~~~~~~
 ``Temporary`` copies are not replicated and will be retained only by the zone
 on which the restore request is initiated.
 
@@ -282,7 +285,7 @@ on which the restore request is initiated.
 
 
 Versioned Objects
-~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~
 For versioned objects, if an object has been cloud-transitioned, it is in a
 non-current state. After a restore, the same non-current object will be
 updated with the downloaded data, and its ``HEAD`` object will be modified accordingly.
diff --git a/doc/radosgw/cloud-sync-module.rst b/doc/radosgw/cloud-sync-module.rst
index a601bd503fbab..1b68c4dd36aed 100644
--- a/doc/radosgw/cloud-sync-module.rst
+++ b/doc/radosgw/cloud-sync-module.rst
@@ -1,6 +1,6 @@
-=========================
+=================
 Cloud Sync Module
-=========================
+=================
 
 .. versionadded:: Mimic
 
@@ -19,10 +19,10 @@ stores these as metadata attributes on the destination objects.
 
 
 Cloud Sync Tier Type Configuration
--------------------------------------
+----------------------------------
 
-Trivial Configuration:
-~~~~~~~~~~~~~~~~~~~~~~
+Trivial Configuration
+~~~~~~~~~~~~~~~~~~~~~
 
 ::
 
@@ -40,25 +40,25 @@ Trivial Configuration:
     }
 
 
-Non Trivial Configuration:
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Non Trivial Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
 
     {
       "default": {
         "connection": {
-            "access_key": <access>,
-            "secret": <secret>,
-            "endpoint": <endpoint>,
-            "host_style" <path | virtual>,
+          "access_key": <access>,
+          "secret": <secret>,
+          "endpoint": <endpoint>,
+          "host_style" <path | virtual>,
         },
         "acls": [
-        {
-          "type" : <id | email | uri>,   #  optional, default is id
-          "source_id": <id>,
-          "dest_id": <id>
-        } ... ]
+          {
+            "type" : <id | email | uri>,    # optional, default is id
+            "source_id": <id>,
+            "dest_id": <id>
+          } ... ],
         "target_path": <path> # optional
       },
       "connections": [
@@ -76,15 +76,15 @@ Non Trivial Configuration:
                 "type": <id | email | uri>,
                 "source_id": <id>,
                 "dest_id": <id>
-              } ... ]
+              } ... ],
           }
       ],
       "profiles": [
           {
-           "source_bucket": <source>,
-           "connection_id": <connection_id>,
-           "acls_id": <mappings_id>,
-           "target_path": <dest>,          # optional
+            "source_bucket": <source>,
+            "connection_id": <connection_id>,
+            "acls_id": <mappings_id>,
+            "target_path": <dest>,          # optional
           } ... ],
     }
 
@@ -140,13 +140,14 @@ ID of user in the destination.
 A string that defines how the target path is created. The target path specifies a prefix to which
 the source object name is appended. The target path configurable can include any of the following
 variables:
-- ``sid``: unique string that represents the sync instance ID
-- ``zonegroup``: the zonegroup name
-- ``zonegroup_id``: the zonegroup ID
-- ``zone``: the zone name
-- ``zone_id``: the zone id
-- ``bucket``: source bucket name
-- ``owner``: source bucket owner ID
+
+* ``sid``: unique string that represents the sync instance ID
+* ``zonegroup``: the zonegroup name
+* ``zonegroup_id``: the zonegroup ID
+* ``zone``: the zone name
+* ``zone_id``: the zone id
+* ``bucket``: source bucket name
+* ``owner``: source bucket owner ID
 
 For example: ``target_path = rgwx-${zone}-${sid}/${owner}/${bucket}``
 
@@ -163,14 +164,15 @@ holds a list of ``acl_mappings``.
 * ``profiles`` (array)
 
 A list of profiles. Each profile contains the following:
-- ``source_bucket``: either a bucket name, or a bucket prefix (if ends with ``*``) that defines the source bucket(s) for this profile
-- ``target_path``: as defined above
-- ``connection_id``: ID of the connection that will be used for this profile
-- ``acls_id``: ID of ACLs profile that will be used for this profile
 
+* ``source_bucket``: either a bucket name, or a bucket prefix (if ends with ``*``) that defines the source bucket(s) for this profile
+* ``target_path``: as defined above
+* ``connection_id``: ID of the connection that will be used for this profile
+* ``acls_id``: ID of ACLs profile that will be used for this profile
 
-S3 Specific Configurables:
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+S3 Specific Configurables
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Currently cloud sync will only work with backends that are compatible with AWS S3. There are
 a few configurables that can be used to tweak its behavior when accessing these cloud services:
@@ -198,30 +200,31 @@ How to Configure
 See :ref:`multisite` for how to multisite config instructions. The cloud sync module requires a creation of a new zone. The zone
 tier type needs to be defined as ``cloud``:
 
-::
+.. prompt:: bash #
 
-    # radosgw-admin zone create --rgw-zonegroup={zone-group-name} \
-                                --rgw-zone={zone-name} \
-                                --endpoints={http://fqdn}[,{http://fqdn}]
-                                --tier-type=cloud
+   radosgw-admin zone create --rgw-zonegroup={zone-group-name} \
+                               --rgw-zone={zone-name} \
+                               --endpoints={http://fqdn}[,{http://fqdn}] \
+                               --tier-type=cloud
 
 
 The tier configuration can be then done using the following command
 
-::
+.. prompt:: bash #
+
+   radosgw-admin zone modify --rgw-zonegroup={zone-group-name} \
+                               --rgw-zone={zone-name} \
+                               --tier-config={key}={val}[,{key}={val}]
 
-    # radosgw-admin zone modify --rgw-zonegroup={zone-group-name} \
-                                --rgw-zone={zone-name} \
-                                --tier-config={key}={val}[,{key}={val}]
 
 The ``key`` in the configuration specifies the config variable that needs to be updated, and
 the ``val`` specifies its new value. Nested values can be accessed using period. For example:
 
-::
+.. prompt:: bash #
 
-    # radosgw-admin zone modify --rgw-zonegroup={zone-group-name} \
-                                --rgw-zone={zone-name} \
-                                --tier-config=connection.access_key={key},connection.secret={secret}
+   radosgw-admin zone modify --rgw-zonegroup={zone-group-name} \
+                               --rgw-zone={zone-name} \
+                               --tier-config=connection.access_key={key},connection.secret={secret}
 
 
 Configuration array entries can be accessed by specifying the specific entry to be referenced enclosed
@@ -230,15 +233,15 @@ the last entry in the array. At the moment it is not possible to create a new en
 again at the same command.
 For example, creating a new profile for buckets starting with {prefix}:
 
-::
+.. prompt:: bash #
 
-    # radosgw-admin zone modify --rgw-zonegroup={zone-group-name} \
-                                --rgw-zone={zone-name} \
-                                --tier-config=profiles[].source_bucket={prefix}'*'
+   radosgw-admin zone modify --rgw-zonegroup={zone-group-name} \
+                               --rgw-zone={zone-name} \
+                               --tier-config=profiles[].source_bucket={prefix}'*'
 
-    # radosgw-admin zone modify --rgw-zonegroup={zone-group-name} \
-                                --rgw-zone={zone-name} \
-                                --tier-config=profiles[-1].connection_id={conn_id},profiles[-1].acls_id={acls_id}
+   radosgw-admin zone modify --rgw-zonegroup={zone-group-name} \
+                               --rgw-zone={zone-name} \
+                               --tier-config=profiles[-1].connection_id={conn_id},profiles[-1].acls_id={acls_id}
 
 
 An entry can be removed by using ``--tier-config-rm={key}``.
diff --git a/doc/radosgw/cloud-transition.rst b/doc/radosgw/cloud-transition.rst
index b87d75e6614d8..d3f7b4def7fd3 100644
--- a/doc/radosgw/cloud-transition.rst
+++ b/doc/radosgw/cloud-transition.rst
@@ -1,6 +1,6 @@
-==================
- Cloud Transition 
-==================
+================
+Cloud Transition
+================
 
 This feature enables transitioning S3 objects to a remote cloud service as part
 of `object lifecycle <https://docs.aws.amazon.com/AmazonS3/latest/dev/object-lifecycle-mgmt.html>`_
@@ -154,18 +154,23 @@ See :ref:`adding_a_storage_class` for how to configure storage-class for a zoneg
           the zone/zonegroup changes will take effect once the changes are
           committed with ``radosgw-admin period update --commit``.
 
-::
+.. prompt:: bash #
 
-  $ radosgw-admin zonegroup placement add --rgw-zonegroup={zone-group-name} \
-                                          --placement-id={placement-id} \
-                                          --storage-class={storage-class-name} \
-                                          --tier-type=cloud-s3 
+   radosgw-admin zonegroup placement add --rgw-zonegroup={zone-group-name} \
+                                           --placement-id={placement-id} \
+                                           --storage-class={storage-class-name} \
+                                           --tier-type=cloud-s3 
 
-For example::
+For example
+
+.. prompt:: bash #
+
+   radosgw-admin zonegroup placement add --rgw-zonegroup=default \
+                                           --placement-id=default-placement \
+                                           --storage-class=CLOUDTIER --tier-type=cloud-s3
+
+::
 
-  $ radosgw-admin zonegroup placement add --rgw-zonegroup=default \
-                                          --placement-id=default-placement \
-                                          --storage-class=CLOUDTIER --tier-type=cloud-s3
   [
       {
           "key": "default-placement",
@@ -207,24 +212,28 @@ For example::
 
 The tier configuration can be then performed using the following command::
 
-  $ radosgw-admin zonegroup placement modify --rgw-zonegroup={zone-group-name} \
-                                             --placement-id={placement-id} \
-                                             --storage-class={storage-class-name} \
-                                             --tier-config={key}={val}[,{key}={val}]
+.. prompt:: bash #
+
+   radosgw-admin zonegroup placement modify --rgw-zonegroup={zone-group-name} \
+                                              --placement-id={placement-id} \
+                                              --storage-class={storage-class-name} \
+                                              --tier-config={key}={val}[,{key}={val}]
 
 The ``key`` in the configuration specifies the config variable to be updated, and
 the ``val`` specifies its new value.
 
 For example::
 
-  $ radosgw-admin zonegroup placement modify --rgw-zonegroup default \
-                                             --placement-id default-placement \
-                                             --storage-class CLOUDTIER \
-                                             --tier-config=endpoint=http://XX.XX.XX.XX:YY,\
-                                             access_key=<access_key>,secret=<secret>, \
-                                             multipart_sync_threshold=44432, \
-                                             multipart_min_part_size=44432, \
-                                             retain_head_object=true
+.. prompt:: bash #
+
+   radosgw-admin zonegroup placement modify --rgw-zonegroup default \
+                                              --placement-id default-placement \
+                                              --storage-class CLOUDTIER \
+                                              --tier-config=endpoint=http://XX.XX.XX.XX:YY,\
+                                              access_key=<access_key>,secret=<secret>, \
+                                              multipart_sync_threshold=44432, \
+                                              multipart_min_part_size=44432, \
+                                              retain_head_object=true
 
 Nested tier configuration values can be accessed using periods. This notation
 works similarly to how nested fields are accessed in JSON with tools like ``jq``.
@@ -232,49 +241,62 @@ Note that the use of period separators ``(.)`` is specific to key access within
 and should not be confused with Ceph RGW patterns for realm/zonegroup/zone. 
 For example::
 
-  $ radosgw-admin zonegroup placement modify --rgw-zonegroup={zone-group-name} \
-                                             --placement-id={placement-id} \
-                                             --storage-class={storage-class-name} \
-                                             --tier-config=acls.source_id=${source-id}, \
-                                             acls.dest_id=${dest-id}
+.. prompt:: bash #
+
+   radosgw-admin zonegroup placement modify --rgw-zonegroup={zone-group-name} \
+                                              --placement-id={placement-id} \
+                                              --storage-class={storage-class-name} \
+                                              --tier-config=acls.source_id=${source-id}, \
+                                              acls.dest_id=${dest-id}
 
 Configuration array entries can be accessed by specifying the specific entry to
 be referenced enclosed in square brackets, and adding a new array entry can be
 performed with an empty array `[]`.
 For example, creating a new ``acl`` array entry::
 
-  $ radosgw-admin zonegroup placement modify --rgw-zonegroup={zone-group-name} \
-                                             --placement-id={placement-id} \
-                                             --storage-class={storage-class-name} \
-                                             --tier-config=acls[].source_id=${source-id}, \
-                                             acls[${source-id}].dest_id=${dest-id}, \
-                                             acls[${source-id}].type=email
+.. prompt:: bash #
+
+   radosgw-admin zonegroup placement modify --rgw-zonegroup={zone-group-name} \
+                                              --placement-id={placement-id} \
+                                              --storage-class={storage-class-name} \
+                                              --tier-config=acls[].source_id=${source-id}, \
+                                              acls[${source-id}].dest_id=${dest-id}, \
+                                              acls[${source-id}].type=email
 
 An entry can be removed by supplying ``--tier-config-rm={key}``.
 
 For example::
 
-  $ radosgw-admin zonegroup placement modify --rgw-zonegroup default \
-                                             --placement-id default-placement \
-                                             --storage-class CLOUDTIER \
-                                             --tier-config-rm=acls.source_id=testid
+.. prompt:: bash #
 
-  $ radosgw-admin zonegroup placement modify --rgw-zonegroup default \
-                                             --placement-id default-placement \
-                                             --storage-class CLOUDTIER \
-                                             --tier-config-rm=target_path
+   radosgw-admin zonegroup placement modify --rgw-zonegroup default \
+                                              --placement-id default-placement \
+                                              --storage-class CLOUDTIER \
+                                              --tier-config-rm=acls.source_id=testid
+
+   radosgw-admin zonegroup placement modify --rgw-zonegroup default \
+                                              --placement-id default-placement \
+                                              --storage-class CLOUDTIER \
+                                              --tier-config-rm=target_path
 
 The storage class can be removed using the following command::
 
-  $ radosgw-admin zonegroup placement rm --rgw-zonegroup={zone-group-name} \
-                                         --placement-id={placement-id} \
-                                         --storage-class={storage-class-name}
+.. prompt:: bash #
 
-For example::
+   radosgw-admin zonegroup placement rm --rgw-zonegroup={zone-group-name} \
+                                          --placement-id={placement-id} \
+                                          --storage-class={storage-class-name}
+
+For example:
+
+.. prompt:: bash #
+
+   radosgw-admin zonegroup placement rm --rgw-zonegroup default \
+                                          --placement-id default-placement \
+                                          --storage-class CLOUDTIER
+
+::
 
-  $ radosgw-admin zonegroup placement rm --rgw-zonegroup default \
-                                         --placement-id default-placement \
-                                         --storage-class CLOUDTIER
   [
       {
           "key": "default-placement",
@@ -289,6 +311,10 @@ For example::
   ]
 
 
+   radosgw-admin zonegroup placement rm --rgw-zonegroup default \
+                                          --placement-id default-placement \
+                                          --storage-class CLOUDTIER
+
 Object Modification and Limitations
 -----------------------------------
 
@@ -345,7 +371,12 @@ objects intact.
 
 For example::
 
-  # s3cmd info s3://bucket/lc.txt
+.. prompt:: bash $
+
+   s3cmd info s3://bucket/lc.txt
+
+::
+
   s3://bucket/lc.txt (object):
      File size: 12
      Last mod:  Mon, 21 Dec 2020 10:25:56 GMT
@@ -358,7 +389,12 @@ For example::
      ACL:       M. Tester: FULL_CONTROL
      x-amz-meta-s3cmd-attrs: atime:1608466266/ctime:1597606156/gid:0/gname:root/md5:ed076287532e86365e841e92bfc50d8c/mode:33188/mtime:1597605793/uid:0/uname:root
   
-  # s3cmd get s3://bucket/lc.txt lc_restore.txt
+.. prompt:: bash $
+
+   s3cmd get s3://bucket/lc.txt lc_restore.txt
+
+::
+
   download: 's3://bucket/lc.txt' -> 'lc_restore.txt'  [1 of 1]
   ERROR: S3 error: 403 (InvalidObjectState)
 
diff --git a/doc/radosgw/multisite-sync-policy.rst b/doc/radosgw/multisite-sync-policy.rst
index 7a6e7105ce637..d377853c44f08 100644
--- a/doc/radosgw/multisite-sync-policy.rst
+++ b/doc/radosgw/multisite-sync-policy.rst
@@ -29,7 +29,7 @@ A sync policy group can be in 3 states:
 
 A policy can be defined at the bucket level. A bucket level sync policy inherits the data flow of the zonegroup policy, and can only define a subset of what the zonegroup allows.
 
-A wildcard zone, and a wildcard bucket parameter in the policy defines all relevant zones, or all relevant buckets. In the context of a bucket policy it means the current bucket instance.  A disaster recovery configuration where entire zones are mirrored doesn't require configuring anything on the buckets. However, for a fine grained bucket sync it would be better to configure the pipes to be synced by allowing (status=allowed) them at the zonegroup level (e.g., using wildcards), but only enable the specific sync at the bucket level (status=enabled). If needed, the policy at the bucket level can limit the data movement to specific relevant zones.
+A wildcard zone, and a wildcard bucket parameter in the policy defines all relevant zones, or all relevant buckets. In the context of a bucket policy it means the current bucket instance.  A disaster recovery configuration where entire zones are mirrored doesn't require configuring anything on the buckets. However, for a fine grained bucket sync it would be better to configure the pipes to be synced by allowing (``status=allowed``) them at the zonegroup level (e.g., using wildcards), but only enable the specific sync at the bucket level (``status=enabled``). If needed, the policy at the bucket level can limit the data movement to specific relevant zones.
 
 .. important:: Any changes to the zonegroup policy needs to be applied on the
                zonegroup master zone, and require period update and commit. Changes
@@ -52,9 +52,9 @@ Get Sync Policy
 
 To retrieve the current zonegroup sync policy, or a specific bucket policy:
 
-::
+.. prompt:: bash #
 
-     # radosgw-admin sync policy get [--bucket=<bucket>]
+   radosgw-admin sync policy get [--bucket=<bucket>]
 
 
 Create Sync Policy Group
@@ -62,46 +62,45 @@ Create Sync Policy Group
 
 To create a sync policy group:
 
-::
+.. prompt:: bash #
+
+   radosgw-admin sync group create [--bucket=<bucket>] \
+                                     --group-id=<group-id> \
+                                     --status=<enabled | allowed | forbidden>
+
 
-      # radosgw-admin sync group create [--bucket=<bucket>]                      \
-                                        --group-id=<group-id>                    \
-                                        --status=<enabled | allowed | forbidden> \
-                                       
-      
 Modify Sync Policy Group
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 To modify a sync policy group:
 
-::
+.. prompt:: bash #
 
-      # radosgw-admin sync group modify [--bucket=<bucket>]                      \
-                                        --group-id=<group-id>                    \
-                                        --status=<enabled | allowed | forbidden> \
+   radosgw-admin sync group modify [--bucket=<bucket>] \
+                                     --group-id=<group-id> \
+                                     --status=<enabled | allowed | forbidden>
 
 
 Show Sync Policy Group
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~
 
 To show a sync policy group:
 
-::
+.. prompt:: bash #
+
+   radosgw-admin sync group get [--bucket=<bucket>] \
+                                  --group-id=<group-id>
 
-      # radosgw-admin sync group get [--bucket=<bucket>]       \
-                                        --group-id=<group-id>
-                                       
 
 Remove Sync Policy Group
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 To remove a sync policy group:
 
-::
-
-      # radosgw-admin sync group remove [--bucket=<bucket>]    \
-                                        --group-id=<group-id>
+.. prompt:: bash #
 
+   radosgw-admin sync group remove [--bucket=<bucket>] \
+                                     --group-id=<group-id>
 
 
 Create Sync Flow
@@ -109,25 +108,25 @@ Create Sync Flow
 
 - To create or update directional sync flow:
 
-::
+.. prompt:: bash #
 
-      # radosgw-admin sync group flow create [--bucket=<bucket>]          \
-                                             --group-id=<group-id>        \
-                                             --flow-id=<flow-id>          \
-                                             --flow-type=directional      \
-                                             --source-zone=<source_zone>  \
-                                             --dest-zone=<dest_zone>
+   radosgw-admin sync group flow create [--bucket=<bucket>] \
+                                          --group-id=<group-id> \
+                                          --flow-id=<flow-id> \
+                                          --flow-type=directional \
+                                          --source-zone=<source_zone> \
+                                          --dest-zone=<dest_zone>
 
 
 - To create or update symmetrical sync flow:
 
-::
+.. prompt:: bash #
 
-      # radosgw-admin sync group flow create [--bucket=<bucket>]          \
-                                             --group-id=<group-id>        \
-                                             --flow-id=<flow-id>          \
-                                             --flow-type=symmetrical      \
-                                             --zones=<zones>
+   radosgw-admin sync group flow create [--bucket=<bucket>] \
+                                          --group-id=<group-id> \
+                                          --flow-id=<flow-id> \
+                                          --flow-type=symmetrical \
+                                          --zones=<zones>
 
 
 Where zones are a comma separated list of all the zones that need to add to the flow.
@@ -138,25 +137,25 @@ Remove Sync Flow Zones
 
 - To remove directional sync flow:
 
-::
+.. prompt:: bash #
 
-      # radosgw-admin sync group flow remove [--bucket=<bucket>]          \
-                                             --group-id=<group-id>        \
-                                             --flow-id=<flow-id>          \
-                                             --flow-type=directional      \
-                                             --source-zone=<source_zone>  \
-                                             --dest-zone=<dest_zone>
+   radosgw-admin sync group flow remove [--bucket=<bucket>] \
+                                          --group-id=<group-id> \
+                                          --flow-id=<flow-id> \
+                                          --flow-type=directional \
+                                          --source-zone=<source_zone> \
+                                          --dest-zone=<dest_zone>
 
 
 - To remove specific zones from symmetrical sync flow:
 
-::
+.. prompt:: bash #
 
-      # radosgw-admin sync group flow remove [--bucket=<bucket>]          \
-                                             --group-id=<group-id>        \
-                                             --flow-id=<flow-id>          \
-                                             --flow-type=symmetrical      \
-                                             --zones=<zones>
+   radosgw-admin sync group flow remove [--bucket=<bucket>] \
+                                          --group-id=<group-id> \
+                                          --flow-id=<flow-id> \
+                                          --flow-type=symmetrical \
+                                          --zones=<zones>
 
 
 Where zones are a comma separated list of all zones to remove from the flow.
@@ -164,12 +163,12 @@ Where zones are a comma separated list of all zones to remove from the flow.
                                              
 - To remove symmetrical sync flow:
 
-::
+.. prompt:: bash #
 
-      # radosgw-admin sync group flow remove [--bucket=<bucket>]          \
-                                             --group-id=<group-id>        \
-                                             --flow-id=<flow-id>          \
-                                             --flow-type=symmetrical
+   radosgw-admin sync group flow remove [--bucket=<bucket>] \
+                                          --group-id=<group-id> \
+                                          --flow-id=<flow-id> \
+                                          --flow-type=symmetrical
 
 
 Create Sync Pipe
@@ -178,25 +177,25 @@ Create Sync Pipe
 To create sync group pipe, or update its parameters:
 
 
-::
+.. prompt:: bash #
 
-      # radosgw-admin sync group pipe create [--bucket=<bucket>]                      \
-                                             --group-id=<group-id>                    \
-                                             --pipe-id=<pipe-id>                      \
-                                             --source-zones=<source_zones>            \
-                                             [--source-bucket=<source_buckets>]       \
-                                             [--source-bucket-id=<source_bucket_id>]  \
-                                             --dest-zones=<dest_zones>                \
-                                             [--dest-bucket=<dest_buckets>]           \
-                                             [--dest-bucket-id=<dest_bucket_id>]      \
-                                             [--prefix=<source_prefix>]               \
-                                             [--prefix-rm]                            \
-                                             [--tags-add=<tags>]                      \
-                                             [--tags-rm=<tags>]                       \
-                                             [--dest-owner=<owner>]                   \
-                                             [--storage-class=<storage_class>]        \
-                                             [--mode=<system | user>]                 \
-                                             [--uid=<user_id>]
+   radosgw-admin sync group pipe create [--bucket=<bucket>] \
+                                          --group-id=<group-id> \
+                                          --pipe-id=<pipe-id> \
+                                          --source-zones=<source_zones> \
+                                          [--source-bucket=<source_buckets>] \
+                                          [--source-bucket-id=<source_bucket_id>] \
+                                          --dest-zones=<dest_zones> \
+                                          [--dest-bucket=<dest_buckets>] \
+                                          [--dest-bucket-id=<dest_bucket_id>] \
+                                          [--prefix=<source_prefix>] \
+                                          [--prefix-rm] \
+                                          [--tags-add=<tags>] \
+                                          [--tags-rm=<tags>] \
+                                          [--dest-owner=<owner>] \
+                                          [--storage-class=<storage_class>] \
+                                          [--mode=<system | user>] \
+                                          [--uid=<user_id>]
 
 
 Zones are either a list of zones, or '*' (wildcard). Wildcard zones mean any zone that matches the sync flow rules.
@@ -214,17 +213,17 @@ Remove Sync Pipe
 To remove specific sync group pipe params, or the entire pipe:
 
 
-::
+.. prompt:: bash #
 
-      # radosgw-admin sync group pipe remove [--bucket=<bucket>]                     \
-                                             --group-id=<group-id>                   \
-                                             --pipe-id=<pipe-id>                     \
-                                             [--source-zones=<source_zones>]         \
-                                             [--source-bucket=<source_buckets>]      \
-                                             [--source-bucket-id=<source_bucket_id>] \
-                                             [--dest-zones=<dest_zones>]             \
-                                             [--dest-bucket=<dest_buckets>]          \
-                                             [--dest-bucket-id=<dest_bucket_id>]
+   radosgw-admin sync group pipe remove [--bucket=<bucket>] \
+                                          --group-id=<group-id> \
+                                          --pipe-id=<pipe-id> \
+                                          [--source-zones=<source_zones>] \
+                                          [--source-bucket=<source_buckets>] \
+                                          [--source-bucket-id=<source_bucket_id>] \
+                                          [--dest-zones=<dest_zones>] \
+                                          [--dest-bucket=<dest_buckets>] \
+                                          [--dest-bucket-id=<dest_bucket_id>]
 
 
 Sync Info
@@ -232,10 +231,10 @@ Sync Info
 
 To get information about the expected sync sources and targets (as defined by the sync policy):
 
-::
+.. prompt:: bash #
 
-      # radosgw-admin sync info [--bucket=<bucket>]             \
-                                [--effective-zone-name=<zone>]
+   radosgw-admin sync info [--bucket=<bucket>] \
+                             [--effective-zone-name=<zone>]
 
 
 Since a bucket can define a policy that defines data movement from it towards a different bucket at a different zone, when the policy is created we also generate a list of bucket dependencies that are used as hints when a sync of any particular bucket happens. The fact that a bucket references another bucket does not mean it actually syncs to/from it, as the data flow might not permit it.  
@@ -252,94 +251,99 @@ Example 1: Two Zones, Complete Mirror
 This is similar to older (pre ``Octopus``) sync capabilities, but being done via the new sync policy engine. Note that changes to the zonegroup sync policy require a period update and commit.
 
 
+.. prompt:: bash [us-east]#
+
+   radosgw-admin sync group create --group-id=group1 --status=allowed
+   radosgw-admin sync group flow create --group-id=group1 \
+                                                   --flow-id=flow-mirror --flow-type=symmetrical \
+                                                   --zones=us-east,us-west
+   radosgw-admin sync group pipe create --group-id=group1 \
+                                                   --pipe-id=pipe1 --source-zones='*' \
+                                                   --source-bucket='*' --dest-zones='*' \
+                                                   --dest-bucket='*'
+   radosgw-admin sync group modify --group-id=group1 --status=enabled
+   radosgw-admin period update --commit
+   radosgw-admin sync info --bucket=buck
+
 ::
 
-      [us-east] $ radosgw-admin sync group create --group-id=group1 --status=allowed
-      [us-east] $ radosgw-admin sync group flow create --group-id=group1 \
-                                --flow-id=flow-mirror --flow-type=symmetrical \
-                                --zones=us-east,us-west
-      [us-east] $ radosgw-admin sync group pipe create --group-id=group1 \
-                                --pipe-id=pipe1 --source-zones='*' \
-                                --source-bucket='*' --dest-zones='*' \
-                                --dest-bucket='*'
-      [us-east] $ radosgw-admin sync group modify --group-id=group1 --status=enabled
-      [us-east] $ radosgw-admin period update --commit
-
-      $ radosgw-admin sync info --bucket=buck
-      {
-          "sources": [
-              {
-                  "id": "pipe1",
-                  "source": {
-                      "zone": "us-west",
-                      "bucket": "buck:115b12b3-....4409.1"
-                  },
-                  "dest": {
-                      "zone": "us-east",
-                      "bucket": "buck:115b12b3-....4409.1"
-                  },
-                  "params": {
-      ...
-                  }
-              }
-          ],
-          "dests": [
-              {
-                  "id": "pipe1",
-                  "source": {
-                      "zone": "us-east",
-                      "bucket": "buck:115b12b3-....4409.1"
-                  },
-                  "dest": {
-                      "zone": "us-west",
-                      "bucket": "buck:115b12b3-....4409.1"
-                  },
-                 ...
-              }
-          ],
-          ...
-          }
-      }
+    {
+        "sources": [
+            {
+                "id": "pipe1",
+                "source": {
+                    "zone": "us-west",
+                    "bucket": "buck:115b12b3-....4409.1"
+                },
+                "dest": {
+                    "zone": "us-east",
+                    "bucket": "buck:115b12b3-....4409.1"
+                },
+                "params": {
+                    ...
+                }
+            }
+        ],
+        "dests": [
+            {
+                "id": "pipe1",
+                "source": {
+                    "zone": "us-east",
+                    "bucket": "buck:115b12b3-....4409.1"
+                },
+                "dest": {
+                    "zone": "us-west",
+                    "bucket": "buck:115b12b3-....4409.1"
+                },
+                ...
+            }
+        ],
+        ...
+        }
+    }
 
 
 Note that the "id" field in the output above reflects the pipe rule
 that generated that entry, a single rule can generate multiple sync
 entries as can be seen in the example.
 
+.. prompt:: bash [us-west]#
+
+   radosgw-admin sync info --bucket=buck
+
 ::
 
-      [us-west] $ radosgw-admin sync info --bucket=buck
-      {
-          "sources": [
-              {
-                  "id": "pipe1",
-                  "source": {
-                      "zone": "us-east",
-                      "bucket": "buck:115b12b3-....4409.1"
-                  },
-                  "dest": {
-                      "zone": "us-west",
-                      "bucket": "buck:115b12b3-....4409.1"
-                  },
-                  ...
-              }
-          ],
-          "dests": [
-              {
-                  "id": "pipe1",
-                  "source": {
-                      "zone": "us-west",
-                      "bucket": "buck:115b12b3-....4409.1"
-                  },
-                  "dest": {
-                      "zone": "us-east",
-                      "bucket": "buck:115b12b3-....4409.1"
-                  },
-                 ...
-              }
-          ],
-          ...
-      }
+    {
+        "sources": [
+            {
+                "id": "pipe1",
+                "source": {
+                    "zone": "us-east",
+                    "bucket": "buck:115b12b3-....4409.1"
+                },
+                "dest": {
+                    "zone": "us-west",
+                    "bucket": "buck:115b12b3-....4409.1"
+                },
+                ...
+            }
+        ],
+        "dests": [
+            {
+                "id": "pipe1",
+                "source": {
+                    "zone": "us-west",
+                    "bucket": "buck:115b12b3-....4409.1"
+                },
+                "dest": {
+                    "zone": "us-east",
+                    "bucket": "buck:115b12b3-....4409.1"
+                },
+                ...
+            }
+        ],
+        ...
+    }
 
 
 
@@ -348,87 +352,93 @@ Example 2: Directional, Entire Zone Backup
 
 Also similar to older sync capabilities. In here we add a third zone, ``us-west-2`` that will be a replica of ``us-west``, but data will not be replicated back from it.
 
-::
+.. prompt:: bash [us-east]#
 
-      [us-east] $ radosgw-admin sync group flow create --group-id=group1 \
-                                --flow-id=us-west-backup --flow-type=directional \
-                                --source-zone=us-west --dest-zone=us-west-2
-      [us-east] $ radosgw-admin period update --commit
+   radosgw-admin sync group flow create --group-id=group1 \
+                                                   --flow-id=us-west-backup --flow-type=directional \
+                                                   --source-zone=us-west --dest-zone=us-west-2
+   radosgw-admin period update --commit
 
 
 Note that us-west has two dests:
 
+.. prompt:: bash [us-west]#
+
+   radosgw-admin sync info --bucket=buck
+
 ::
 
-      [us-west] $ radosgw-admin sync info --bucket=buck
-      {
-          "sources": [
-              {
-                  "id": "pipe1",
-                  "source": {
-                      "zone": "us-east",
-                      "bucket": "buck:115b12b3-....4409.1"
-                  },
-                  "dest": {
-                      "zone": "us-west",
-                      "bucket": "buck:115b12b3-....4409.1"
-                  },
-                 ...
-              }
-          ],
-          "dests": [
-              {
-                  "id": "pipe1",
-                  "source": {
-                      "zone": "us-west",
-                      "bucket": "buck:115b12b3-....4409.1"
-                  },
-                  "dest": {
-                      "zone": "us-east",
-                      "bucket": "buck:115b12b3-....4409.1"
-                  },
-                 ...
-              },
-              {
-                  "id": "pipe1",
-                  "source": {
-                      "zone": "us-west",
-                      "bucket": "buck:115b12b3-....4409.1"
-                  },
-                  "dest": {
-                      "zone": "us-west-2",
-                      "bucket": "buck:115b12b3-....4409.1"
-                  },
-                 ...
-              }
-          ],
-          ...
-      }
+    {
+        "sources": [
+            {
+                "id": "pipe1",
+                "source": {
+                    "zone": "us-east",
+                    "bucket": "buck:115b12b3-....4409.1"
+                },
+                "dest": {
+                    "zone": "us-west",
+                    "bucket": "buck:115b12b3-....4409.1"
+                },
+                ...
+            }
+        ],
+        "dests": [
+            {
+                "id": "pipe1",
+                "source": {
+                    "zone": "us-west",
+                    "bucket": "buck:115b12b3-....4409.1"
+                },
+                "dest": {
+                    "zone": "us-east",
+                    "bucket": "buck:115b12b3-....4409.1"
+                },
+                ...
+            },
+            {
+                "id": "pipe1",
+                "source": {
+                    "zone": "us-west",
+                    "bucket": "buck:115b12b3-....4409.1"
+                },
+                "dest": {
+                    "zone": "us-west-2",
+                    "bucket": "buck:115b12b3-....4409.1"
+                },
+                ...
+            }
+        ],
+        ...
+    }
 
 
 Whereas us-west-2 has only source and no destinations:
 
+.. prompt:: bash [us-west-2]#
+
+   radosgw-admin sync info --bucket=buck
+
 ::
 
-      [us-west-2] $ radosgw-admin sync info --bucket=buck
-      {
-          "sources": [
-              {
-                  "id": "pipe1",
-                  "source": {
-                      "zone": "us-west",
-                      "bucket": "buck:115b12b3-....4409.1"
-                  },
-                  "dest": {
-                      "zone": "us-west-2",
-                      "bucket": "buck:115b12b3-....4409.1"
-                  },
-                 ...
-              }
-          ],
-          "dests": [],
-          ...
-      }
+    {
+        "sources": [
+            {
+                "id": "pipe1",
+                "source": {
+                    "zone": "us-west",
+                    "bucket": "buck:115b12b3-....4409.1"
+                },
+                "dest": {
+                    "zone": "us-west-2",
+                    "bucket": "buck:115b12b3-....4409.1"
+                },
+                ...
+            }
+        ],
+        "dests": [],
+        ...
+    }
 
       
       
@@ -437,38 +447,36 @@ Example 3: Mirror a Specific Bucket
 
 Using the same group configuration, but this time switching it to ``allowed`` state, which means that sync is allowed but not enabled.
 
-::
+.. prompt:: bash [us-east]#
 
-      [us-east] $ radosgw-admin sync group modify --group-id=group1 --status=allowed
-      [us-east] $ radosgw-admin period update --commit
+   radosgw-admin sync group modify --group-id=group1 --status=allowed
+   radosgw-admin period update --commit
 
 
 And we will create a bucket level policy rule for existing bucket ``buck2``. Note that the bucket needs to exist before being able to set this policy, and admin commands that modify bucket policies need to run on the master zone, however, they do not require period update.  There is no need to change the data flow, as it is inherited from the zonegroup policy. A bucket policy flow will only be a subset of the flow defined in the zonegroup policy. Same goes for pipes, although a bucket policy can enable pipes that are not enabled (albeit not forbidden) at the zonegroup policy.
 
-::
-
-      [us-east] $ radosgw-admin sync group create --bucket=buck2 \
-                                --group-id=buck2-default --status=enabled
+.. prompt:: bash [us-east]#
 
-      [us-east] $ radosgw-admin sync group pipe create --bucket=buck2 \
-                                --group-id=buck2-default --pipe-id=pipe1 \
-                                --source-zones='*' --dest-zones='*'
+   radosgw-admin sync group create --bucket=buck2 \
+                                              --group-id=buck2-default --status=enabled
+   radosgw-admin sync group pipe create --bucket=buck2 \
+                                                   --group-id=buck2-default --pipe-id=pipe1 \
+                                                   --source-zones='*' --dest-zones='*'
 
 
 
-Example 4: Limit Bucket Sync To Specific Zones
+Example 4: Limit Bucket Sync to Specific Zones
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This will only sync ``buck3`` to ``us-east`` (from any zone that flow allows to sync into ``us-east``).
 
-::
-
-      [us-east] $ radosgw-admin sync group create --bucket=buck3 \
-                                --group-id=buck3-default --status=enabled
+.. prompt:: bash [us-east]#
 
-      [us-east] $ radosgw-admin sync group pipe create --bucket=buck3 \
-                                --group-id=buck3-default --pipe-id=pipe1 \
-                                --source-zones='*' --dest-zones=us-east
+   radosgw-admin sync group create --bucket=buck3 \
+                                              --group-id=buck3-default --status=enabled
+   radosgw-admin sync group pipe create --bucket=buck3 \
+                                                   --group-id=buck3-default --pipe-id=pipe1 \
+                                                   --source-zones='*' --dest-zones=us-east
 
 
 
@@ -479,97 +487,98 @@ Note that bucket sync only works (currently) across zones and not within the sam
 
 Set ``buck4`` to pull data from ``buck5``:
 
-::
-
-      [us-east] $ radosgw-admin sync group create --bucket=buck4 '
-                                --group-id=buck4-default --status=enabled
+.. prompt:: bash [us-east]#
 
-      [us-east] $ radosgw-admin sync group pipe create --bucket=buck4 \
-                                --group-id=buck4-default --pipe-id=pipe1 \
-                                --source-zones='*' --source-bucket=buck5 \
-                                --dest-zones='*'
+   radosgw-admin sync group create --bucket=buck4 \
+                                              --group-id=buck4-default --status=enabled
+   radosgw-admin sync group pipe create --bucket=buck4 \
+                                                   --group-id=buck4-default --pipe-id=pipe1 \
+                                                   --source-zones='*' --source-bucket=buck5 \
+                                                   --dest-zones='*'
 
 
 can also limit it to specific zones, for example the following will
 only sync data originated in us-west:
 
-::
+.. prompt:: bash [us-east]#
 
-      [us-east] $ radosgw-admin sync group pipe modify --bucket=buck4 \
-                                --group-id=buck4-default --pipe-id=pipe1 \
-                                --source-zones=us-west --source-bucket=buck5 \
-                                --dest-zones='*'
+   radosgw-admin sync group pipe modify --bucket=buck4 \
+                                                   --group-id=buck4-default --pipe-id=pipe1 \
+                                                   --source-zones=us-west --source-bucket=buck5 \
+                                                   --dest-zones='*'
 
 
 Checking the sync info for ``buck5`` on ``us-west`` is interesting:
 
+.. prompt:: bash [us-west]#
+
+   radosgw-admin sync info --bucket=buck5
+
 ::
 
-      [us-west] $ radosgw-admin sync info --bucket=buck5
-      {
-          "sources": [],
-          "dests": [],
-          "hints": {
-              "sources": [],
-              "dests": [
-                  "buck4:115b12b3-....14433.2"
-              ]
-          },
-          "resolved-hints-1": {
-              "sources": [],
-              "dests": [
-                  {
-                      "id": "pipe1",
-                      "source": {
-                          "zone": "us-west",
-                          "bucket": "buck5"
-                      },
-                      "dest": {
-                          "zone": "us-east",
-                          "bucket": "buck4:115b12b3-....14433.2"
-                      },
-                      ...
-                  },
-                  {
-                      "id": "pipe1",
-                      "source": {
-                          "zone": "us-west",
-                          "bucket": "buck5"
-                      },
-                      "dest": {
-                          "zone": "us-west-2",
-                          "bucket": "buck4:115b12b3-....14433.2"
-                      },
-                      ...
-                  }
-              ]
-          },
-          "resolved-hints": {
-              "sources": [],
-              "dests": []
-          }
-      }
+    {
+        "sources": [],
+        "dests": [],
+        "hints": {
+            "sources": [],
+            "dests": [
+                "buck4:115b12b3-....14433.2"
+            ]
+        },
+        "resolved-hints-1": {
+            "sources": [],
+            "dests": [
+                {
+                    "id": "pipe1",
+                    "source": {
+                        "zone": "us-west",
+                        "bucket": "buck5"
+                    },
+                    "dest": {
+                        "zone": "us-east",
+                        "bucket": "buck4:115b12b3-....14433.2"
+                    },
+                    ...
+                },
+                {
+                    "id": "pipe1",
+                    "source": {
+                        "zone": "us-west",
+                        "bucket": "buck5"
+                    },
+                    "dest": {
+                        "zone": "us-west-2",
+                        "bucket": "buck4:115b12b3-....14433.2"
+                    },
+                    ...
+                }
+            ]
+        },
+        "resolved-hints": {
+            "sources": [],
+            "dests": []
+        }
+    }
 
 
 Note that there are resolved hints, which means that the bucket ``buck5`` found about ``buck4`` syncing from it indirectly, and not from its own policy (the policy for ``buck5`` itself is empty).
 
 
-Example 6: Sync To Different Bucket
+Example 6: Sync to Different Bucket
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The same mechanism can work for configuring data to be synced to (vs.  synced from as in the previous example). Note that internally data is still pulled from the source at the destination zone:
 
 Set ``buck6`` to "push" data to ``buck5``:
 
-::
-
-      [us-east] $ radosgw-admin sync group create --bucket=buck6 \
-                                --group-id=buck6-default --status=enabled
+.. prompt:: bash [us-east]#
 
-      [us-east] $ radosgw-admin sync group pipe create --bucket=buck6 \
-                                --group-id=buck6-default --pipe-id=pipe1 \
-                                --source-zones='*' --source-bucket='*' \
-                                --dest-zones='*' --dest-bucket=buck5
+   radosgw-admin sync group create --bucket=buck6 \
+                                              --group-id=buck6-default --status=enabled
+   radosgw-admin sync group pipe create --bucket=buck6 \
+                                                   --group-id=buck6-default --pipe-id=pipe1 \
+                                                   --source-zones='*' --source-bucket='*' \
+                                                   --dest-zones='*' --dest-bucket=buck5
 
 
 A wildcard bucket name means the current bucket in the context of bucket sync policy.
@@ -581,86 +590,88 @@ Example 7: Source Filters
 
 Sync from ``buck8`` to ``buck9``, but only objects that start with ``foo/``:
 
-::
-
-      [us-east] $ radosgw-admin sync group create --bucket=buck8 \
-                                --group-id=buck8-default --status=enabled
+.. prompt:: bash [us-east]#
 
-      [us-east] $ radosgw-admin sync group pipe create --bucket=buck8 \
-                                --group-id=buck8-default --pipe-id=pipe-prefix \
-                                --prefix=foo/ --source-zones='*' --dest-zones='*' \
-                                --dest-bucket=buck9
+   radosgw-admin sync group create --bucket=buck8 \
+                                              --group-id=buck8-default --status=enabled
+   radosgw-admin sync group pipe create --bucket=buck8 \
+                                                   --group-id=buck8-default --pipe-id=pipe-prefix \
+                                                   --prefix=foo/ --source-zones='*' --dest-zones='*' \
+                                                   --dest-bucket=buck9
 
 
 Also sync from ``buck8`` to ``buck9`` any object that has the tags ``color=blue`` or ``color=red``:
 
-::
+.. prompt:: bash [us-east]#
 
-      [us-east] $ radosgw-admin sync group pipe create --bucket=buck8 \
-                                --group-id=buck8-default --pipe-id=pipe-tags \
-                                --tags-add=color=blue,color=red --source-zones='*' \
-                                --dest-zones='*' --dest-bucket=buck9
+   radosgw-admin sync group pipe create --bucket=buck8 \
+                                                   --group-id=buck8-default --pipe-id=pipe-tags \
+                                                   --tags-add=color=blue,color=red --source-zones='*' \
+                                                   --dest-zones='*' --dest-bucket=buck9
 
 
 And we can check the expected sync in ``us-east`` (for example):
 
+.. prompt:: bash [us-east]#
+
+   radosgw-admin sync info --bucket=buck8
+
 ::
 
-      [us-east] $ radosgw-admin sync info --bucket=buck8
-      {
-          "sources": [],
-          "dests": [
-              {
-                  "id": "pipe-prefix",
-                  "source": {
-                      "zone": "us-east",
-                      "bucket": "buck8:115b12b3-....14433.5"
-                  },
-                  "dest": {
-                      "zone": "us-west",
-                      "bucket": "buck9"
-                  },
-                  "params": {
-                      "source": {
-                          "filter": {
-                              "prefix": "foo/",
-                              "tags": []
-                          }
-                      },
-                      ...
-                  }
-              },
-              {
-                  "id": "pipe-tags",
-                  "source": {
-                      "zone": "us-east",
-                      "bucket": "buck8:115b12b3-....14433.5"
-                  },
-                  "dest": {
-                      "zone": "us-west",
-                      "bucket": "buck9"
-                  },
-                  "params": {
-                      "source": {
-                          "filter": {
-                              "tags": [
-                                  {
-                                      "key": "color",
-                                      "value": "blue"
-                                  },
-                                  {
-                                      "key": "color",
-                                      "value": "red"
-                                  }
-                              ]
-                          }
-                      },
-                      ...
-                  }
-              }
-          ],
-          ...
-      }
+    {
+        "sources": [],
+        "dests": [
+            {
+                "id": "pipe-prefix",
+                "source": {
+                    "zone": "us-east",
+                    "bucket": "buck8:115b12b3-....14433.5"
+                },
+                "dest": {
+                    "zone": "us-west",
+                    "bucket": "buck9"
+                },
+                "params": {
+                    "source": {
+                        "filter": {
+                            "prefix": "foo/",
+                            "tags": []
+                        }
+                    },
+                    ...
+                }
+            },
+            {
+                "id": "pipe-tags",
+                "source": {
+                    "zone": "us-east",
+                    "bucket": "buck8:115b12b3-....14433.5"
+                },
+                "dest": {
+                    "zone": "us-west",
+                    "bucket": "buck9"
+                },
+                "params": {
+                    "source": {
+                        "filter": {
+                            "tags": [
+                                {
+                                    "key": "color",
+                                    "value": "blue"
+                                },
+                                {
+                                    "key": "color",
+                                    "value": "red"
+                                }
+                            ]
+                        }
+                    },
+                    ...
+                }
+            }
+        ],
+        ...
+    }
 
 
 Note that there aren't any sources, only two different destinations (one for each configuration). When the sync process happens it will select the relevant rule for each object it syncs.
@@ -673,16 +684,15 @@ Example 8: Destination Params: Storage Class
 
 Storage class of the destination objects can be configured:
 
-::
-
-      [us-east] $ radosgw-admin sync group create --bucket=buck10 \
-                                --group-id=buck10-default --status=enabled
+.. prompt:: bash [us-east]#
 
-      [us-east] $ radosgw-admin sync group pipe create --bucket=buck10 \
-                                --group-id=buck10-default \
-                                --pipe-id=pipe-storage-class \
-                                --source-zones='*' --dest-zones=us-west-2 \
-                                --storage-class=CHEAP_AND_SLOW
+   radosgw-admin sync group create --bucket=buck10 \
+                                              --group-id=buck10-default --status=enabled
+   radosgw-admin sync group pipe create --bucket=buck10 \
+                                                   --group-id=buck10-default \
+                                                   --pipe-id=pipe-storage-class \
+                                                   --source-zones='*' --dest-zones=us-west-2 \
+                                                   --storage-class=CHEAP_AND_SLOW
 
 
 Example 9: Destination Params: Destination Owner Translation
@@ -691,26 +701,26 @@ Example 9: Destination Params: Destination Owner Translation
 Set the destination objects owner as the destination bucket owner.
 This requires specifying the uid of the destination bucket:
 
-::
+.. prompt:: bash [us-east]#
 
-      [us-east] $ radosgw-admin sync group create --bucket=buck11 \
-                                --group-id=buck11-default --status=enabled
+   radosgw-admin sync group create --bucket=buck11 \
+                                              --group-id=buck11-default --status=enabled
+   radosgw-admin sync group pipe create --bucket=buck11 \
+                                                   --group-id=buck11-default --pipe-id=pipe-dest-owner \
+                                                   --source-zones='*' --dest-zones='*' \
+                                                   --dest-bucket=buck12 --dest-owner=joe
 
-      [us-east] $ radosgw-admin sync group pipe create --bucket=buck11 \
-                                --group-id=buck11-default --pipe-id=pipe-dest-owner \
-                                --source-zones='*' --dest-zones='*' \
-                                --dest-bucket=buck12 --dest-owner=joe
 
 Example 10: Destination Params: User Mode
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 User mode makes sure that the user has permissions to both read the objects, and write to the destination bucket. This requires that the uid of the user (which in its context the operation executes) is specified.
 
-::
+.. prompt:: bash [us-east]#
 
-      [us-east] $ radosgw-admin sync group pipe modify --bucket=buck11 \
-                                --group-id=buck11-default --pipe-id=pipe-dest-owner \
-                                --mode=user --uid=jenny
+   radosgw-admin sync group pipe modify --bucket=buck11 \
+                                                   --group-id=buck11-default --pipe-id=pipe-dest-owner \
+                                                   --mode=user --uid=jenny
 
 
 
diff --git a/doc/radosgw/sync-modules.rst b/doc/radosgw/sync-modules.rst
index 61797edc857c8..53f16c70cb3a9 100644
--- a/doc/radosgw/sync-modules.rst
+++ b/doc/radosgw/sync-modules.rst
@@ -32,7 +32,7 @@ for configuring any sync plugin
    Archive Sync Module <archive-sync-module>
 
 .. note ``rgw`` is the default sync plugin and there is no need to explicitly
-   configure this
+   configure this.
 
 Requirements and Assumptions
 ----------------------------
@@ -50,25 +50,24 @@ Configuring Sync Modules
 
 Create the third zone similar to the :ref:`multisite` docs, for example
 
-::
-
-   # radosgw-admin zone create --rgw-zonegroup=us --rgw-zone=us-east-es \
-   --access-key={system-key} --secret={secret} --endpoints=http://rgw-es:80
+.. prompt:: bash #
 
+   radosgw-admin zone create --rgw-zonegroup=us --rgw-zone=us-east-es \
+                               --access-key={system-key} --secret={secret} --endpoints=http://rgw-es:80
 
 
 A sync module can be configured for this zone via the following
 
-::
+.. prompt:: bash #
 
-   # radosgw-admin zone modify --rgw-zone={zone-name} --tier-type={tier-type} --tier-config={set of key=value pairs}
+   radosgw-admin zone modify --rgw-zone={zone-name} --tier-type={tier-type} --tier-config={set of key=value pairs}
 
 
 For example in the ``elasticsearch`` sync module
 
-::
+.. prompt:: bash #
 
-   # radosgw-admin zone modify --rgw-zone={zone-name} --tier-type=elasticsearch \
+   radosgw-admin zone modify --rgw-zone={zone-name} --tier-type=elasticsearch \
                                --tier-config=endpoint=http://localhost:9200,num_shards=10,num_replicas=1
 
 
@@ -76,18 +75,17 @@ For the various supported tier-config options refer to the `elasticsearch sync m
 
 Finally update the period
 
+.. prompt:: bash #
 
-::
-
-    # radosgw-admin period update --commit
+   radosgw-admin period update --commit
 
 
 Now start the radosgw in the zone
 
-::
+.. prompt:: bash #
 
-    # systemctl start ceph-radosgw@rgw.`hostname -s`
-    # systemctl enable ceph-radosgw@rgw.`hostname -s`
+   systemctl start ceph-radosgw@rgw.`hostname -s`
+   systemctl enable ceph-radosgw@rgw.`hostname -s`
 
 
 


Reviews:
user: login: anthonyeleven
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-10T17:02:57Z
user: login: bluikko
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-10T17:09:52Z
user: login: bluikko
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-10T17:11:37Z
user: login: bluikko
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-10T17:12:52Z
user: login: bluikko
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-10T17:17:31Z
user: login: anthonyeleven
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-10T17:21:30Z
user: login: bluikko
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-10T17:24:10Z
user: login: anthonyeleven
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-10T17:31:58Z
user: login: bluikko
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-11T03:05:16Z
user: login: bluikko
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-11T04:51:41Z
user: login: anthonyeleven
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-16T13:38:01Z
user: login: anthonyeleven
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-16T13:53:18Z
user: login: anthonyeleven
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-16T13:58:09Z

Review comments:
diff_hunk: @@ -12,23 +12,22 @@ S3-compatible cloud services. In order to faciliate this,
 the ``retain_head_object`` option should be set to ``true``
 in the ``tier-config`` when configuring the storage class.
 
-Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`
-PI . The restored copies will be retained within RGW only for the number
+Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`_
+API. The restored copies will be retained within RGW only for the number
 of ``days`` specified. However if ``days`` is not provided, the restored copies
 are considered permanent and will be treated as regular objects.
 In addition, by enabling the ``allow_read_through`` option,
-the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`
+the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`_
 API can be used to restore the object temporarily.
 
 
 Cloud Storage Class Tier Configuration
 --------------------------------------
 
-The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`
+The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`_
path: doc/radosgw/cloud-restore.rst
user: login: anthonyeleven
body: What is the importance of the trailing underscore?
created_at: 2025-04-10T17:01:50Z
author_association: CONTRIBUTOR
diff_hunk: @@ -12,23 +12,22 @@ S3-compatible cloud services. In order to faciliate this,
 the ``retain_head_object`` option should be set to ``true``
 in the ``tier-config`` when configuring the storage class.
 
-Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`
-PI . The restored copies will be retained within RGW only for the number
+Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`_
+API. The restored copies will be retained within RGW only for the number
 of ``days`` specified. However if ``days`` is not provided, the restored copies
 are considered permanent and will be treated as regular objects.
 In addition, by enabling the ``allow_read_through`` option,
-the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`
+the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`_
 API can be used to restore the object temporarily.
 
 
 Cloud Storage Class Tier Configuration
 --------------------------------------
 
-The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`
+The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`_
 of the cloud storage class configured for data transition is used to restore
-objects as well:
+objects as well::
path: doc/radosgw/cloud-restore.rst
user: login: anthonyeleven
body: Why double colon?
created_at: 2025-04-10T17:01:59Z
author_association: CONTRIBUTOR
diff_hunk: @@ -12,23 +12,22 @@ S3-compatible cloud services. In order to faciliate this,
 the ``retain_head_object`` option should be set to ``true``
 in the ``tier-config`` when configuring the storage class.
 
-Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`
-PI . The restored copies will be retained within RGW only for the number
+Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`_
+API. The restored copies will be retained within RGW only for the number
 of ``days`` specified. However if ``days`` is not provided, the restored copies
 are considered permanent and will be treated as regular objects.
 In addition, by enabling the ``allow_read_through`` option,
-the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`
+the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`_
 API can be used to restore the object temporarily.
 
 
 Cloud Storage Class Tier Configuration
 --------------------------------------
 
-The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`
+The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`_
path: doc/radosgw/cloud-restore.rst
user: login: bluikko
body: Without the trailing underscore it is not recognized as a hyperlink, it's all rendered in text but just italic. Check out https://docs.ceph.com/en/latest/radosgw/cloud-restore/ vs https://ceph--62763.org.readthedocs.build/en/62763/radosgw/cloud-restore/
created_at: 2025-04-10T17:09:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -12,23 +12,22 @@ S3-compatible cloud services. In order to faciliate this,
 the ``retain_head_object`` option should be set to ``true``
 in the ``tier-config`` when configuring the storage class.
 
-Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`
-PI . The restored copies will be retained within RGW only for the number
+Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`_
+API. The restored copies will be retained within RGW only for the number
 of ``days`` specified. However if ``days`` is not provided, the restored copies
 are considered permanent and will be treated as regular objects.
 In addition, by enabling the ``allow_read_through`` option,
-the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`
+the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`_
 API can be used to restore the object temporarily.
 
 
 Cloud Storage Class Tier Configuration
 --------------------------------------
 
-The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`
+The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`_
 of the cloud storage class configured for data transition is used to restore
-objects as well:
+objects as well::
path: doc/radosgw/cloud-restore.rst
user: login: bluikko
body: It will render the following block as a code block. This is used in some other files. The triple backtick is just rendered as-is and does not create a code block like in markdown.
created_at: 2025-04-10T17:11:37Z
author_association: CONTRIBUTOR
diff_hunk: @@ -12,23 +12,22 @@ S3-compatible cloud services. In order to faciliate this,
 the ``retain_head_object`` option should be set to ``true``
 in the ``tier-config`` when configuring the storage class.
 
-Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`
-PI . The restored copies will be retained within RGW only for the number
+Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`_
+API. The restored copies will be retained within RGW only for the number
 of ``days`` specified. However if ``days`` is not provided, the restored copies
 are considered permanent and will be treated as regular objects.
 In addition, by enabling the ``allow_read_through`` option,
-the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`
+the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`_
 API can be used to restore the object temporarily.
 
 
 Cloud Storage Class Tier Configuration
 --------------------------------------
 
-The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`
+The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`_
 of the cloud storage class configured for data transition is used to restore
-objects as well:
+objects as well::
path: doc/radosgw/cloud-restore.rst
user: login: bluikko
body: Ah, right, I forgot to list this change in the PR / commit description sorry for that. 
created_at: 2025-04-10T17:12:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -12,23 +12,22 @@ S3-compatible cloud services. In order to faciliate this,
 the ``retain_head_object`` option should be set to ``true``
 in the ``tier-config`` when configuring the storage class.
 
-Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`
-PI . The restored copies will be retained within RGW only for the number
+Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`_
+API. The restored copies will be retained within RGW only for the number
 of ``days`` specified. However if ``days`` is not provided, the restored copies
 are considered permanent and will be treated as regular objects.
 In addition, by enabling the ``allow_read_through`` option,
-the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`
+the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`_
 API can be used to restore the object temporarily.
 
 
 Cloud Storage Class Tier Configuration
 --------------------------------------
 
-The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`
+The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`_
 of the cloud storage class configured for data transition is used to restore
-objects as well:
+objects as well::
path: doc/radosgw/cloud-restore.rst
user: login: bluikko
body: Oof, more of these both (link missing underscore and triple backtick) also in `cloud-transition.rst` but I think this PR is fat enough as is. Will leave it for tomorrow if that's fine.  
Added the double colon in PR description.
created_at: 2025-04-10T17:17:31Z
author_association: CONTRIBUTOR
diff_hunk: @@ -12,23 +12,22 @@ S3-compatible cloud services. In order to faciliate this,
 the ``retain_head_object`` option should be set to ``true``
 in the ``tier-config`` when configuring the storage class.
 
-Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`
-PI . The restored copies will be retained within RGW only for the number
+Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`_
+API. The restored copies will be retained within RGW only for the number
 of ``days`` specified. However if ``days`` is not provided, the restored copies
 are considered permanent and will be treated as regular objects.
 In addition, by enabling the ``allow_read_through`` option,
-the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`
+the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`_
 API can be used to restore the object temporarily.
 
 
 Cloud Storage Class Tier Configuration
 --------------------------------------
 
-The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`
+The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`_
 of the cloud storage class configured for data transition is used to restore
-objects as well:
+objects as well::
path: doc/radosgw/cloud-restore.rst
user: login: anthonyeleven
body: In most cases I think we use a double backtick; I don't recall a triple anywhere but that doesn't mean it doesn't happen.  Remember that we use Sphinx vs the Markdown one might see on GitHub, sometimes there are rendering subtleties.  If you have an improved strategy for code / command blocks, I'm all ears, I'll ask though that you lay out the distinctions for me.


created_at: 2025-04-10T17:21:30Z
author_association: CONTRIBUTOR
diff_hunk: @@ -12,23 +12,22 @@ S3-compatible cloud services. In order to faciliate this,
 the ``retain_head_object`` option should be set to ``true``
 in the ``tier-config`` when configuring the storage class.
 
-Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`
-PI . The restored copies will be retained within RGW only for the number
+Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`_
+API. The restored copies will be retained within RGW only for the number
 of ``days`` specified. However if ``days`` is not provided, the restored copies
 are considered permanent and will be treated as regular objects.
 In addition, by enabling the ``allow_read_through`` option,
-the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`
+the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`_
 API can be used to restore the object temporarily.
 
 
 Cloud Storage Class Tier Configuration
 --------------------------------------
 
-The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`
+The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`_
 of the cloud storage class configured for data transition is used to restore
-objects as well:
+objects as well::
path: doc/radosgw/cloud-restore.rst
user: login: bluikko
body: I see I forgot to check `cloud-transition.rst` as rendered -- this PR did touch that file, too. I can either update this PR tomorrow (out of time now) or do a different PR, which do you prefer?
created_at: 2025-04-10T17:24:10Z
author_association: CONTRIBUTOR
diff_hunk: @@ -12,23 +12,22 @@ S3-compatible cloud services. In order to faciliate this,
 the ``retain_head_object`` option should be set to ``true``
 in the ``tier-config`` when configuring the storage class.
 
-Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`
-PI . The restored copies will be retained within RGW only for the number
+Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`_
+API. The restored copies will be retained within RGW only for the number
 of ``days`` specified. However if ``days`` is not provided, the restored copies
 are considered permanent and will be treated as regular objects.
 In addition, by enabling the ``allow_read_through`` option,
-the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`
+the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`_
 API can be used to restore the object temporarily.
 
 
 Cloud Storage Class Tier Configuration
 --------------------------------------
 
-The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`
+The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`_
 of the cloud storage class configured for data transition is used to restore
-objects as well:
+objects as well::
path: doc/radosgw/cloud-restore.rst
user: login: anthonyeleven
body: updating this one would be my pref.  Some of the lines you touch are ones that I very recently edited myself.
created_at: 2025-04-10T17:31:58Z
author_association: CONTRIBUTOR
diff_hunk: @@ -12,23 +12,22 @@ S3-compatible cloud services. In order to faciliate this,
 the ``retain_head_object`` option should be set to ``true``
 in the ``tier-config`` when configuring the storage class.
 
-Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`
-PI . The restored copies will be retained within RGW only for the number
+Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`_
+API. The restored copies will be retained within RGW only for the number
 of ``days`` specified. However if ``days`` is not provided, the restored copies
 are considered permanent and will be treated as regular objects.
 In addition, by enabling the ``allow_read_through`` option,
-the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`
+the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`_
 API can be used to restore the object temporarily.
 
 
 Cloud Storage Class Tier Configuration
 --------------------------------------
 
-The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`
+The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`_
 of the cloud storage class configured for data transition is used to restore
-objects as well:
+objects as well::
path: doc/radosgw/cloud-restore.rst
user: login: bluikko
body: Double backtick seems to be for code inline, not a code block?

It would seem double colon is the syntax to use for a code block. Is the question then whether that double colon should be on its own line by itself, or can it be merged to the preceding single colon at the end of the previous text paragraph?

So either something like:
```
text paragraph here. For example::

    code block
```

or

```
text paragraph here. For example:

::

    code block
```

I also do see sometimes
```
.. code-block::

    code-block
```
The double colon at the end of a text paragraph renders as a single colon & creates a code block. It seems to be used at least in `doc/ceph-volume/` and `doc/cephadm/`; also the third example seems to be used in `doc/cephdm/`.

I guess it's a matter of personal preference or policy how to do this.
created_at: 2025-04-11T03:05:16Z
author_association: CONTRIBUTOR
diff_hunk: @@ -12,23 +12,22 @@ S3-compatible cloud services. In order to faciliate this,
 the ``retain_head_object`` option should be set to ``true``
 in the ``tier-config`` when configuring the storage class.
 
-Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`
-PI . The restored copies will be retained within RGW only for the number
+Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`_
+API. The restored copies will be retained within RGW only for the number
 of ``days`` specified. However if ``days`` is not provided, the restored copies
 are considered permanent and will be treated as regular objects.
 In addition, by enabling the ``allow_read_through`` option,
-the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`
+the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`_
 API can be used to restore the object temporarily.
 
 
 Cloud Storage Class Tier Configuration
 --------------------------------------
 
-The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`
+The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`_
path: doc/radosgw/cloud-restore.rst
user: login: bluikko
body: Regarding this particular link in your OP. I just realized that links inside Ceph documentation surely must not be hardcoded URLs and they should be links to a RST reference instead?

A grep of `doc/` seems to confirm this, there are very very few hyperlinks pointing to `https://docs.ceph.com/`.

This is how this whole PR became a rabbit hole: every revision I noticed masses of more things to "improve" (some arguably very minor or opinionated).
created_at: 2025-04-11T04:51:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -12,23 +12,22 @@ S3-compatible cloud services. In order to faciliate this,
 the ``retain_head_object`` option should be set to ``true``
 in the ``tier-config`` when configuring the storage class.
 
-Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`
-PI . The restored copies will be retained within RGW only for the number
+Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`_
+API. The restored copies will be retained within RGW only for the number
 of ``days`` specified. However if ``days`` is not provided, the restored copies
 are considered permanent and will be treated as regular objects.
 In addition, by enabling the ``allow_read_through`` option,
-the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`
+the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`_
 API can be used to restore the object temporarily.
 
 
 Cloud Storage Class Tier Configuration
 --------------------------------------
 
-The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`
+The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`_
path: doc/radosgw/cloud-restore.rst
user: login: anthonyeleven
body: >This is how this whole PR became a rabbit hole: every revision I noticed masses of more things to "improve" (some arguably very minor or opinionated).

Welcome to my world :D

We call this "making a clean spot"

https://www.youtube.com/watch?v=qMmzIp5ubqM

>Without the trailing underscore it is not recognized as a hyperlink, it's all rendered in text but just italic.

Ack. 

>A grep of doc/ seems to confirm this, there are very very few hyperlinks pointing to https://docs.ceph.com/.
`

Really there shouldn't be any, we should be using `:ref:` perhaps, but it seems to work without that.  For sure we should not be using explicit URLs to refer to other parts of our own documentation, as the FQDN may change over time, and we may render into different forms, so please do feel free to update any links of the above form.




created_at: 2025-04-16T13:38:01Z
author_association: CONTRIBUTOR
diff_hunk: @@ -12,23 +12,22 @@ S3-compatible cloud services. In order to faciliate this,
 the ``retain_head_object`` option should be set to ``true``
 in the ``tier-config`` when configuring the storage class.
 
-Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`
-PI . The restored copies will be retained within RGW only for the number
+Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`_
+API. The restored copies will be retained within RGW only for the number
 of ``days`` specified. However if ``days`` is not provided, the restored copies
 are considered permanent and will be treated as regular objects.
 In addition, by enabling the ``allow_read_through`` option,
-the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`
+the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`_
 API can be used to restore the object temporarily.
 
 
 Cloud Storage Class Tier Configuration
 --------------------------------------
 
-The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`
+The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`_
 of the cloud storage class configured for data transition is used to restore
-objects as well:
+objects as well::
path: doc/radosgw/cloud-restore.rst
user: login: anthonyeleven
body: Hmmm:

>The "code" directive constructs a literal block. If the code language is specified, the content is parsed by the [Pygments](https://pygments.org/) syntax highlighter and tokens are stored in nested [inline elements](https://docutils.sourceforge.io/docs/ref/doctree.html#inline-elements) with class arguments according to their syntactic category.

and

>A paragraph consisting of two colons (::) signifies that the following text block(s) comprise a literal block. The literal block must either be indented or quoted (see below). No markup processing is done within a literal block. It is left as-is, and is typically rendered in a monospaced typeface:

I think when we deal with classic Markdown, Slack Markdown, GitHub Markdown, and RST on the same day it's all too easy to mix up the contexts.

Looking into this I think we should probably be using the

```
text paragraph here. For example:

::

    code block

```
form and not worry so much about language-specific highlighting.  Compared to triple backticks I think this renders with a shaded background.

created_at: 2025-04-16T13:53:17Z
author_association: CONTRIBUTOR

PR comments:
user: login: ceph-jenkins
created_at: 2025-04-10T10:47:31Z
body: Can one of the admins verify this patch?
author_association: COLLABORATOR
user: login: bluikko
created_at: 2025-04-10T16:24:12Z
body: Massive amount of small fixes. The RGW sync docs seem they could use a lot of love, for example daemon names in text (often called just "rgw") etc. general polish.

I will make another PR about the section titles in `multisite-sync-policy.rst` they are very wrong and the TOC at the left sidebar is not right because of it.  

Second to-do looks like the config reference in https://docs.ceph.com/en/latest/radosgw/cloud-sync-module/#non-trivial-configuration , the description text for each list item should probably be indented somehow, also there should be two child lists for path & profile syntax. This might be its own PR as right now I'm not sure how to do this in RST.

This one should be ready for review after I check the rendered docs, I am afraid there's already too many changes in this PR.
author_association: CONTRIBUTOR
user: login: bluikko
created_at: 2025-04-10T17:38:36Z
body: Fixed more links and markdownisms in `cloud-transition.rst`, also fixed indentation in multiline promptified CLI commands. Will confirm it's all fixed after the PR rendering pipeline job is complete.
author_association: CONTRIBUTOR
user: login: bluikko
created_at: 2025-04-10T17:49:53Z
body: OK `cloud-transitions.rst` has the same fixes done as other files.  
Indenting multiline commands had problems I had created and was missing some of my fixes after the initial commit. I couldn't just leave it like that.

This PR is "really, really ready" now and should have all rendered docs now checked including `cloud-transitions.rst` that I missed earlier. 
author_association: CONTRIBUTOR
user: login: anthonyeleven
created_at: 2025-04-11T05:16:19Z
body: Indeed links should be relative.  On Apr 11, 2025, at 12:52 AM, Ville Ojamo ***@***.***> wrote:﻿
@bluikko commented on this pull request.



In doc/radosgw/cloud-restore.rst:
>  API can be used to restore the object temporarily.
 
 
 Cloud Storage Class Tier Configuration
 --------------------------------------
 
-The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`
+The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`_

Regarding this particular link in your OP. I just realized that links inside Ceph documentation surely must not be hardcoded URLs and they should be links to a RST reference instead?
A grep of doc/ seems to confirm this, there are very very few hyperlinks pointing to https://docs.ceph.com/.

—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because your review was requested.Message ID: ***@***.***>
author_association: CONTRIBUTOR
user: login: bluikko
created_at: 2025-04-11T08:19:40Z
body: First of all thank you for bearing with me.  
If you would like to take this discussion to some other forum I'm happy to do that, I can create Slack account for example so that we can have a more quick exchange.

I have gone through all the 6 files changed by this PR and confirmed that the current state of the PR could be mergeable with no new errors caused by this PR and the rendered documents looking as I intended them.  
If you have some specific change requests or feedback I will address it ASAP.

Meanwhile, respectfully, I would like to discuss hyperlinks in some more detail. I might be misunderstanding what exactly you mean with "relative" links; I was trying to point out that any such "hardcoded" link might be discouraged whether absolute or relative and RST references might be preferable.  
This is emphasized by the fact that the "hardcoded" link that prompted this discussion in https://github.com/ceph/ceph/pull/62763#discussion_r2037882763 is actually a broken link, the anchor does not exist and following the link results in top of the document instead of the relevant section/anchor `cloud-storage-class-configuration`.

Please note that I am by no means an expert in RST, I may get terminology and details wrong but I'm basing this mostly on the Sphinx documentation below and how the files in `doc/` usually do things.

> Indeed links should be relative.

I meant RST references like the ones listed here in the documentation: https://www.sphinx-doc.org/en/master/usage/referencing.html#cross-referencing-arbitrary-locations

So there are a few different ways to create hyperlinks, I will list here 3 using RST features and 1 using hardcoded URLs (whether absolute or relative).  
Using RST references will create automatic link labels, for example if I add a reference just preceding a section with title `Multisite Configuration` then the link to that reference will automatically get the correct link text/label of "Multisite Configuration".  
Or I could directly link to a section using the section title text, without adding a reference in the destination document but this would break anchors in links if the section title is ever changed.

1) Linking to an RST reference when a specific section in the middle a document needs to be linked (like in this case the intended rendered link ends in an anchor), example:
   ```
   See `Multisite Configuration`_ for multisite configuration instructions.
   ```
   This `Multisite Configuration` could be an RST item such as section title text or a custom defined anchor such as:
   ```
   .. _Multisite Configuration: ../multisite
   ```

2) Linking to an RST reference similarly as above but with different syntax, I believe this is about the same as the option (1) above:
   ```
   :ref:`ceph-volume-lvm`
   ```
   And the reference that the hyperlink points to is defined similarly as same as above option (1). For example here the above link to reference `ceph-volume-lvm` will automatically get the link text/label from the section title ("`lvm`"):
   ```
   doc/ceph-volume/lvm/index.rst:.. _ceph-volume-lvm:
   doc/ceph-volume/lvm/index.rst-
   doc/ceph-volume/lvm/index.rst-``lvm``
   doc/ceph-volume/lvm/index.rst-=======
   ```

3) Linking a document name without an anchor in the intended link, in effect linking to the beginning of the document:
   ```
   :doc:`cloud-transition`
   ```

4) I believe this would be discouraged, a hardcoded link using HTML feature to an URL whether relative or absolute:
   ```
   `upmap <../rados/operations/upmap>`_
   ```

Some statistics from the `doc/` code base:
- 28k RST hyperlinks of the above variety (1).
- 631 RST hyperlinks of the above variety (2)
- 162 RST hyperlinks of the above variety (3).
- 120 hardcoded relative links of the above variety (4)  
   Almost all of them point to "special" content such as man pages and changelog .txt files, and not to RST files.
- Only 15 hardcoded absolute links of the above variety (4) to docs.ceph.com.

These statistics point to _RST references being the preferred method of hyperlinking to other RST content_, which seems logical. These are metadata inside the documentation and not tied to structure on the file system or the resulting URLs as rendered for the web server that may be changed over time resulting in broken links (I believe these are not linted to detect such cases??).

```
$ fgrep '`_' -R doc/ |wc -l
28767
$ fgrep ':ref:`' -R doc/ |wc -l
631
$ fgrep ':doc:`' -R doc/ |wc -l
162
$ fgrep '<../' -R doc/ |wc -l
120
$ fgrep '<https://docs.ceph.com' -R doc/ |wc -l
15
```
author_association: CONTRIBUTOR
user: login: anthonyeleven
created_at: 2025-04-11T15:25:37Z
body: I’ll follow up in more detail this weekend.

I suggest joining the Ceph Slack workspace : https://join.slack.com/t/ceph-storage/shared_invite/zt-32uc4bnb5-rEWQpR5cdGIjmdyUozY8iw

Where there is a #ceph-doc channel

Best to have discussions whee others can contribute.


> On Apr 11, 2025, at 4:20 AM, Ville Ojamo ***@***.***> wrote:
> 
> 
> bluikko
>  left a comment 
> (ceph/ceph#62763)
> First of all thank you for bearing with me.
> If you would like to take this discussion to some other forum I'm happy to do that, I can create Slack account for example so that we can have a more quick exchange.
> 
> I have gone through all the 6 files changed by this PR and confirmed that the current state of the PR could be mergeable with no new errors caused by this PR and the rendered documents looking as I intended them.
> If you have some specific change requests or feedback I will address it ASAP.
> 
> Meanwhile, respectfully, I would like to discuss hyperlinks in some more detail. I might be misunderstanding what exactly you mean with "relative" links; I was trying to point out that any such "hardcoded" link might be discouraged whether absolute or relative and RST references might be preferable.
> This is underlined by the fact that the "hardcoded" link that prompted this discussion in #62763 (comment) is actually a broken link, the anchor does not exist and following the link results in top of the document instead of the relevant section/anchor cloud-storage-class-configuration.
> 
> Please note that I am by no means an expert in RST, I may get terminology and details wrong but I'm basing this mostly on the Sphinx documentation below and how the files in doc/ usually do things.
> 
> Indeed links should be relative.
> 
> I meant RST references like the ones listed here in the documentation: https://www.sphinx-doc.org/en/master/usage/referencing.html#cross-referencing-arbitrary-locations
> 
> So there are a few different ways to create hyperlinks, I will list here 3 using RST features and 1 using hardcoded URLs (whether absolute or relative).
> Using RST references will create automatic link labels, for example if I add a reference just preceding a section with title Multisite Configuration then the link to that reference will automatically get the correct link text/label of "Multisite Configuration".
> Or I could directly link to a section using the section title text, without adding a reference in the destination document but this would break anchors in links if the section title is ever changed.
> 
> Linking to an RST reference when a specific section in the middle a document needs to be linked (like in this case the intended rendered link ends in an anchor), example:
> 
> See `Multisite Configuration`_ for multisite configuration instructions.
> This Multisite Configuration could be an RST item such as section title text or a custom defined anchor such as:
> 
> .. _Multisite Configuration: ../multisite
> Linking to an RST reference similarly as above but with different syntax, I believe this is about the same as the option (1) above:
> 
> :ref:`ceph-volume-lvm`
> And the reference that the hyperlink points to is defined similarly as same as above option (1). For example here the above link to reference ceph-volume-lvm will automatically get the link text/label from the section title ("lvm"):
> 
> doc/ceph-volume/lvm/index.rst:.. _ceph-volume-lvm:
> doc/ceph-volume/lvm/index.rst-
> doc/ceph-volume/lvm/index.rst-``lvm``
> doc/ceph-volume/lvm/index.rst-=======
> Linking a document name without an anchor in the intended link, in effect linking to the beginning of the document:
> 
> :doc:`cloud-transition`
> I believe this would be discouraged, a hardcoded link using HTML feature to an URL whether relative or absolute:
> 
> `upmap <../rados/operations/upmap>`_
> Some statistics from the doc/ code base:
> 
> 28k RST references of the above variety (1).
> 631 RST references of the above variety (2)
> 162 RST references of the above variety (3).
> 120 hardcoded relative links of the above variety (4)
> Almost all of them point to "special" content such as man pages and changelog .txt files, and not to RST files.
> Only 15 hardcoded absolute links of the above variety (4) to docs.ceph.com.
> These statistics point to RST references being the preferred method of linking other RST content, which seems logical. These are metadata inside the documentation and not tied to structure on the file system or the resulting URLs as rendered for the web server that may be changed over time resulting in broken links (I believe these are not linted to detect such cases??).
> 
> $ fgrep '`_' -R doc/ |wc -l
> 28767
> $ fgrep ':ref:`' -R doc/ |wc -l
> 631
> $ fgrep ':doc:`' -R doc/ |wc -l
> 162
> $ fgrep '<../' -R doc/ |wc -l
> 120
> $ fgrep '<https://docs.ceph.com' -R doc/ |wc -l
> 15
> —
> Reply to this email directly, view it on GitHub, or unsubscribe.
> You are receiving this because your review was requested.
> 
>  <https://github.com/ceph/ceph/pull/62763#discussion_r2037882763> <https://www.sphinx-doc.org/en/master/usage/referencing.html#cross-referencing-arbitrary-locations> <https://github.com/ceph/ceph/pull/62763#issuecomment-2796187940> <https://github.com/notifications/unsubscribe-auth/ADTVONEI3E4UPG3EKVN4XYT2Y53LJAVCNFSM6AAAAAB23JJ2HSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDOOJWGE4DOOJUGA>
> 
> bluikko
>  left a comment 
> (ceph/ceph#62763)
>  <https://github.com/ceph/ceph/pull/62763#issuecomment-2796187940>
> First of all thank you for bearing with me.
> If you would like to take this discussion to some other forum I'm happy to do that, I can create Slack account for example so that we can have a more quick exchange.
> 
> I have gone through all the 6 files changed by this PR and confirmed that the current state of the PR could be mergeable with no new errors caused by this PR and the rendered documents looking as I intended them.
> If you have some specific change requests or feedback I will address it ASAP.
> 
> Meanwhile, respectfully, I would like to discuss hyperlinks in some more detail. I might be misunderstanding what exactly you mean with "relative" links; I was trying to point out that any such "hardcoded" link might be discouraged whether absolute or relative and RST references might be preferable.
> This is underlined by the fact that the "hardcoded" link that prompted this discussion in #62763 (comment) <https://github.com/ceph/ceph/pull/62763#discussion_r2037882763> is actually a broken link, the anchor does not exist and following the link results in top of the document instead of the relevant section/anchor cloud-storage-class-configuration.
> 
> Please note that I am by no means an expert in RST, I may get terminology and details wrong but I'm basing this mostly on the Sphinx documentation below and how the files in doc/ usually do things.
> 
> Indeed links should be relative.
> 
> I meant RST references like the ones listed here in the documentation: https://www.sphinx-doc.org/en/master/usage/referencing.html#cross-referencing-arbitrary-locations
> 
> So there are a few different ways to create hyperlinks, I will list here 3 using RST features and 1 using hardcoded URLs (whether absolute or relative).
> Using RST references will create automatic link labels, for example if I add a reference just preceding a section with title Multisite Configuration then the link to that reference will automatically get the correct link text/label of "Multisite Configuration".
> Or I could directly link to a section using the section title text, without adding a reference in the destination document but this would break anchors in links if the section title is ever changed.
> 
> Linking to an RST reference when a specific section in the middle a document needs to be linked (like in this case the intended rendered link ends in an anchor), example:
> 
> See `Multisite Configuration`_ for multisite configuration instructions.
> This Multisite Configuration could be an RST item such as section title text or a custom defined anchor such as:
> 
> .. _Multisite Configuration: ../multisite
> Linking to an RST reference similarly as above but with different syntax, I believe this is about the same as the option (1) above:
> 
> :ref:`ceph-volume-lvm`
> And the reference that the hyperlink points to is defined similarly as same as above option (1). For example here the above link to reference ceph-volume-lvm will automatically get the link text/label from the section title ("lvm"):
> 
> doc/ceph-volume/lvm/index.rst:.. _ceph-volume-lvm:
> doc/ceph-volume/lvm/index.rst-
> doc/ceph-volume/lvm/index.rst-``lvm``
> doc/ceph-volume/lvm/index.rst-=======
> Linking a document name without an anchor in the intended link, in effect linking to the beginning of the document:
> 
> :doc:`cloud-transition`
> I believe this would be discouraged, a hardcoded link using HTML feature to an URL whether relative or absolute:
> 
> `upmap <../rados/operations/upmap>`_
> Some statistics from the doc/ code base:
> 
> 28k RST references of the above variety (1).
> 631 RST references of the above variety (2)
> 162 RST references of the above variety (3).
> 120 hardcoded relative links of the above variety (4)
> Almost all of them point to "special" content such as man pages and changelog .txt files, and not to RST files.
> Only 15 hardcoded absolute links of the above variety (4) to docs.ceph.com.
> These statistics point to RST references being the preferred method of linking other RST content, which seems logical. These are metadata inside the documentation and not tied to structure on the file system or the resulting URLs as rendered for the web server that may be changed over time resulting in broken links (I believe these are not linted to detect such cases??).
> 
> $ fgrep '`_' -R doc/ |wc -l
> 28767
> $ fgrep ':ref:`' -R doc/ |wc -l
> 631
> $ fgrep ':doc:`' -R doc/ |wc -l
> 162
> $ fgrep '<../' -R doc/ |wc -l
> 120
> $ fgrep '<https://docs.ceph.com' -R doc/ |wc -l
> 15
> —
> Reply to this email directly, view it on GitHub <https://github.com/ceph/ceph/pull/62763#issuecomment-2796187940>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADTVONEI3E4UPG3EKVN4XYT2Y53LJAVCNFSM6AAAAAB23JJ2HSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDOOJWGE4DOOJUGA>.
> You are receiving this because your review was requested.
> 


author_association: CONTRIBUTOR
user: login: github-actions[bot]
created_at: 2025-04-15T21:55:12Z
body: This pull request can no longer be automatically merged: a rebase is needed and changes have to be manually resolved
author_association: NONE
user: login: anthonyeleven
created_at: 2025-04-16T13:57:52Z
body: Not sure I see a reason to discourage #4

author_association: CONTRIBUTOR
user: login: anthonyeleven
created_at: 2025-04-16T13:58:32Z
body: If the rendering in the checks looks good, I think we're okay to merge?
author_association: CONTRIBUTOR
user: login: zdover23
created_at: 2025-04-17T02:55:20Z
body: > If the rendering in the checks looks good, I think we're okay to merge?

I'm going to merge and backport this to S and to R.
author_association: CONTRIBUTOR
user: login: zdover23
created_at: 2025-04-17T03:10:02Z
body: https://github.com/ceph/ceph/pull/62856 - Squid backport
https://github.com/ceph/ceph/pull/62857 - Reef backport
author_association: CONTRIBUTOR