From: Ville Ojamo <14869000+bluikko@users.noreply.github.com>
Date: Thu, 5 Mar 2026 09:02:42 +0000 (+0700)
Subject: doc: Improve start/quick-rbd.rst
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=f418c03d34527fc0583f71b9cb7a83763bdb8f72;p=ceph.git

doc: Improve start/quick-rbd.rst

Remove mention of FAQ with a broken link.
Use ref for intra-docs links and add labels in destination documents.
Promptify all CLI example commands.
Use standard angle brackets for mandatory arguments in commands.
Remove an unused external link definition.
Trim spaces at end of lines and convert tabs to spaces.

Signed-off-by: Ville Ojamo <git2233+ceph@ojamo.eu>
---

diff --git a/doc/man/8/rbdmap.rst b/doc/man/8/rbdmap.rst
index 1a9096a998e..11383e2aafc 100644
--- a/doc/man/8/rbdmap.rst
+++ b/doc/man/8/rbdmap.rst
@@ -1,5 +1,7 @@
 :orphan:
 
+.. _rbdmap:
+
 =========================================
  rbdmap -- map RBD devices at boot time
 =========================================
diff --git a/doc/rbd/index.rst b/doc/rbd/index.rst
index 96f1e138978..983d0c36fb7 100644
--- a/doc/rbd/index.rst
+++ b/doc/rbd/index.rst
@@ -1,3 +1,5 @@
+.. _ceph_block_device:
+
 ===================
  Ceph Block Device
 ===================
diff --git a/doc/start/quick-rbd.rst b/doc/start/quick-rbd.rst
index c1cf7709881..3c095355895 100644
--- a/doc/start/quick-rbd.rst
+++ b/doc/start/quick-rbd.rst
@@ -18,52 +18,56 @@ before working with the :term:`Ceph Block Device`.
            \------------------/         \----------------/
 
 
-You may use a virtual machine for your ``ceph-client`` node, but do not 
-execute the following procedures on the same physical node as your Ceph 
-Storage Cluster nodes (unless you use a VM). See `FAQ`_ for details.
+You may use a virtual machine for your ``ceph-client`` node, but do not
+execute the following procedures on the same physical node as your Ceph
+Storage Cluster nodes (unless you use a VM).
 
 Create a Block Device Pool
 ==========================
 
-#. On the admin node, use the ``ceph`` tool to `create a pool`_
+#. On the admin node, use the ``ceph`` tool to :ref:`create a pool <createpool>`
    (we recommend the name 'rbd').
 
-#. On the admin node, use the ``rbd`` tool to initialize the pool for use by RBD::
+#. On the admin node, use the ``rbd`` tool to initialize the pool for use by RBD:
 
-        rbd pool init <pool-name>
+   .. prompt:: bash $
+
+      rbd pool init <pool-name>
 
 Configure a Block Device
 ========================
 
-#. On the ``ceph-client`` node, create a block device image. :: 
+#. On the ``ceph-client`` node, create a block device image.
 
-	rbd create foo --size 4096 --image-feature layering [-m {mon-IP}] [-k /path/to/ceph.client.admin.keyring] [-p {pool-name}]
+   .. prompt:: bash $
 
-#. On the ``ceph-client`` node, map the image to a block device. :: 
+      rbd create foo --size 40G [-m <mon-IP>] [-k /path/to/ceph.client.admin.keyring] [-p <pool-name>]
 
-	sudo rbd map foo --name client.admin [-m {mon-IP}] [-k /path/to/ceph.client.admin.keyring] [-p {pool-name}]
-	
-#. Use the block device by creating a file system on the ``ceph-client`` 
-   node. :: 
+#. On the ``ceph-client`` node, map the image to a block device.
 
-	sudo mkfs.ext4 -m0 /dev/rbd/{pool-name}/foo
-	
-	This may take a few moments.
-	
-#. Mount the file system on the ``ceph-client`` node. ::
+   .. prompt:: bash $
 
-	sudo mkdir /mnt/ceph-block-device
-	sudo mount /dev/rbd/{pool-name}/foo /mnt/ceph-block-device
-	cd /mnt/ceph-block-device
+      sudo rbd map foo [-m <mon-IP>] [-k /path/to/ceph.client.admin.keyring] [-p <pool-name>]
 
-#. Optionally configure the block device to be automatically mapped and mounted
-   at boot (and unmounted/unmapped at shutdown) - see the `rbdmap manpage`_.
+#. Use the block device by creating a file system on the ``ceph-client``
+   node.
+
+   .. prompt:: bash $
+
+      sudo mkfs.ext4 -m0 /dev/rbd/<pool-name>/foo
+
+   This may take a few moments.
 
+#. Mount the file system on the ``ceph-client`` node.
+
+   .. prompt:: bash $
+
+      sudo mkdir /mnt/ceph-block-device
+      sudo mount /dev/rbd/<pool-name>/foo /mnt/ceph-block-device
+      cd /mnt/ceph-block-device
+
+#. Optionally configure the block device to be automatically mapped and mounted
+   at boot (and unmounted/unmapped at shutdown) - see the :ref:`rbdmap manpage <rbdmap>`.
 
-See `block devices`_ for additional details.
+See :ref:`ceph_block_device` for additional details.
 
-.. _create a pool: ../../rados/operations/pools/#create-a-pool
-.. _block devices: ../../rbd
-.. _FAQ: http://wiki.ceph.com/How_Can_I_Give_Ceph_a_Try
-.. _OS Recommendations: ../os-recommendations
-.. _rbdmap manpage: ../../man/8/rbdmap