Merge pull request ceph#62782 from bluikko/doc-prompts-mgr

doc/mgr: Promptify CLI commands and other formatting fixes

Reviewed-by: Zac Dover <[email protected]>

Author: zdover23

doc/mgr/administrator.rst

@@ -10,21 +10,27 @@ Usually, you would set up a ceph-mgr daemon using a tool such
 as ceph-ansible.  These instructions describe how to set up
 a ceph-mgr daemon manually.
 
-First, create an authentication key for your daemon::
+First, create an authentication key for your daemon:
 
-    ceph auth get-or-create mgr.$name mon 'allow profile mgr' osd 'allow *' mds 'allow *'
+.. prompt:: bash #
+
+   ceph auth get-or-create mgr.$name mon 'allow profile mgr' osd 'allow *' mds 'allow *'
 
 Place that key as file named ``keyring`` into ``mgr data`` path, which for a cluster "ceph"
 and mgr $name "foo" would be ``/var/lib/ceph/mgr/ceph-foo`` respective ``/var/lib/ceph/mgr/ceph-foo/keyring``.
 
-Start the ceph-mgr daemon::
+Start the ceph-mgr daemon:
+
+.. prompt:: bash #
 
-    ceph-mgr -i $name
+   ceph-mgr -i $name
 
 Check that the mgr has come up by looking at the output
-of ``ceph status``, which should now include a mgr status line::
+of ``ceph status``, which should now include a mgr status line:
+
+.. prompt:: bash #
 
-    mgr active: $name
+   mgr active: $name
 
 Client authentication
 ---------------------
@@ -33,7 +39,7 @@ The manager is a new daemon which requires new CephX capabilities. If you upgrad
 a cluster from an old version of Ceph, or use the default install/deploy tools,
 your admin client should get this capability automatically. If you use tooling from
 elsewhere, you may get EACCES errors when invoking certain ceph cluster commands.
-To fix that, add a "mgr allow \*" stanza to your client's cephx capabilities by
+To fix that, add a ``mgr allow \*`` stanza to your client's cephx capabilities by
 `Modifying User Capabilities`_.
 
 High availability
@@ -95,9 +101,12 @@ information about what functionality each module provides.
 
 Here is an example of enabling the :term:`Dashboard` module:
 
-.. code-block:: console
+.. prompt:: bash #
+
+   ceph mgr module ls
+
+::
 
-	$ ceph mgr module ls
 	{
 		"enabled_modules": [
 			"status"
@@ -107,8 +116,13 @@ Here is an example of enabling the :term:`Dashboard` module:
 		]
 	}
 
-	$ ceph mgr module enable dashboard
-	$ ceph mgr module ls
+.. prompt:: bash #
+
+   ceph mgr module enable dashboard
+   ceph mgr module ls
+
+::
+
 	{
 		"enabled_modules": [
 			"status",
@@ -118,7 +132,12 @@ Here is an example of enabling the :term:`Dashboard` module:
 		]
 	}
 
-	$ ceph mgr services
+.. prompt:: bash #
+
+   ceph mgr services
+
+::
+
 	{
 		"dashboard": "http://myserver.com:7789/"
 	}
@@ -157,9 +176,11 @@ Calling module commands
 Where a module implements command line hooks, the commands will
 be accessible as ordinary Ceph commands.  Ceph will automatically incorporate
 module commands into the standard CLI interface and route them appropriately to
-the module.::
+the module.
+
+.. prompt:: bash #
 
-    ceph <command | help>
+   ceph <command | help>
 
 Configuration
 -------------

doc/mgr/alerts.rst

@@ -16,44 +16,58 @@ as well.
 Enabling
 --------
 
-The *alerts* module is enabled with::
+The *alerts* module is enabled with:
 
-  ceph mgr module enable alerts
+.. prompt:: bash #
+
+   ceph mgr module enable alerts
 
 Configuration
 -------------
 
 To configure SMTP, all of the following config options must be set
-(When setting ``mgr/alerts/smtp_destination``, you can use commas to separate multiple)::
+(When setting ``mgr/alerts/smtp_destination``, you can use commas to separate multiple):
+
+.. prompt:: bash #
+
+   ceph config set mgr mgr/alerts/smtp_host *<smtp-server>*
+   ceph config set mgr mgr/alerts/smtp_destination *<email-address-to-send-to>*
+   ceph config set mgr mgr/alerts/smtp_sender *<from-email-address>*
+
+By default, the module will use SSL and port 465.  To change that:
 
-  ceph config set mgr mgr/alerts/smtp_host *<smtp-server>*
-  ceph config set mgr mgr/alerts/smtp_destination *<email-address-to-send-to>*
-  ceph config set mgr mgr/alerts/smtp_sender *<from-email-address>*
+.. prompt:: bash #
 
-By default, the module will use SSL and port 465.  To change that,::
+   ceph config set mgr mgr/alerts/smtp_ssl false   # if not SSL
+   ceph config set mgr mgr/alerts/smtp_port *<port-number>*  # if not 465
 
-  ceph config set mgr mgr/alerts/smtp_ssl false   # if not SSL
-  ceph config set mgr mgr/alerts/smtp_port *<port-number>*  # if not 465
+To authenticate to the SMTP server, you must set the user and password:
 
-To authenticate to the SMTP server, you must set the user and password::
+.. prompt:: bash #
 
-  ceph config set mgr mgr/alerts/smtp_user *<username>*
-  ceph config set mgr mgr/alerts/smtp_password *<password>*
+   ceph config set mgr mgr/alerts/smtp_user *<username>*
+   ceph config set mgr mgr/alerts/smtp_password *<password>*
 
 By default, the name in the ``From:`` line is simply ``Ceph``.  To
-change that (e.g., to identify which cluster this is),::
+change that (e.g., to identify which cluster this is):
 
-  ceph config set mgr mgr/alerts/smtp_from_name 'Ceph Cluster Foo'
+.. prompt:: bash #
+
+   ceph config set mgr mgr/alerts/smtp_from_name 'Ceph Cluster Foo'
 
 By default, the module will check the cluster health once per minute
 and, if there is a change, send a message.  To change that
-frequency,::
+frequency:
+
+.. prompt:: bash #
 
-  ceph config set mgr mgr/alerts/interval *<interval>*   # e.g., "5m" for 5 minutes
+   ceph config set mgr mgr/alerts/interval *<interval>*   # e.g., "5m" for 5 minutes
 
 Commands
 --------
 
-To force an alert to be send immediately,::
+To force an alert to be send immediately:
+
+.. prompt:: bash #
 
-  ceph alerts send
+   ceph alerts send

doc/mgr/ceph_api/index.rst

@@ -53,9 +53,11 @@ be obtained, and it may then be reused for subsequent requests. The
     { "token": "<redacted_token>", ...}
 
 The token obtained must be passed together with every API request in the
-``Authorization`` HTTP header::
+``Authorization`` HTTP header:
 
-  curl -H "Authorization: Bearer <token>" ...
+.. prompt:: bash $
+
+   curl -H "Authorization: Bearer <token>" ...
 
 Authentication and authorization can be further configured from the
 Ceph CLI, the Ceph-Dashboard UI and the Ceph API itself (please refer to

doc/mgr/cli_api.rst

@@ -7,33 +7,47 @@ benchmarked for further testing.
 Enabling
 --------
 
-The *cli api commands* module is enabled with::
+The *cli api commands* module is enabled with:
 
-  ceph mgr module enable cli_api
+.. prompt:: bash #
 
-To check that it is enabled, run::
+   ceph mgr module enable cli_api
 
-  ceph mgr module ls | grep cli_api
+To check that it is enabled, run:
+
+.. prompt:: bash #
+
+   ceph mgr module ls | grep cli_api
 
 Usage
 --------
 
-To run a mgr module command, run::
+To run a mgr module command, run:
+
+.. prompt:: bash #
+
+   ceph mgr cli <command> <param>
+
+For example, use the following command to print the list of servers:
+
+.. prompt:: bash #
+
+   ceph mgr cli list_servers
 
-  ceph mgr cli <command> <param>
+List all available mgr module commands with:
 
-For example, use the following command to print the list of servers::
+.. prompt:: bash #
 
-  ceph mgr cli list_servers
+   ceph mgr cli --help
 
-List all available mgr module commands with::
+To benchmark a command, run:
 
-  ceph mgr cli --help
+.. prompt:: bash #
 
-To benchmark a command, run::
+   ceph mgr cli_benchmark <number of calls> <number of threads> <command> <param>
 
-  ceph mgr cli_benchmark <number of calls> <number of threads> <command> <param>
+For example, use the following command to benchmark the command to get osd_map:
 
-For example, use the following command to benchmark the command to get osd_map::
+.. prompt:: bash #
 
-  ceph mgr cli_benchmark 100 10 get osd_map
+   ceph mgr cli_benchmark 100 10 get osd_map

doc/mgr/crash.rst

@@ -6,13 +6,17 @@ it in the Ceph cluster for later analysis.
 Enabling
 --------
 
-The *crash* module is enabled with::
+The *crash* module is enabled with:
 
-  ceph mgr module enable crash
+.. prompt:: bash #
 
-The *crash* upload key is generated with::
+   ceph mgr module enable crash
 
-  ceph auth get-or-create client.crash mon 'profile crash' mgr 'profile crash'
+The *crash* upload key is generated with:
+
+.. prompt:: bash #
+
+   ceph auth get-or-create client.crash mon 'profile crash' mgr 'profile crash'
 
 On each node, you should store this key in
 ``/etc/ceph/ceph.client.crash.keyring``.
@@ -39,57 +43,57 @@ and a keyring needs to be in ``/etc/ceph``.
 
 Commands
 --------
-::
+.. prompt:: bash #
 
-  ceph crash post -i <metafile>
+   ceph crash post -i <metafile>
 
 Save a crash dump.  The metadata file is a JSON blob stored in the crash
 dir as ``meta``.  As usual, the ceph command can be invoked with ``-i -``,
 and will read from stdin.
 
-::
+.. prompt:: bash #
 
-  ceph crash rm <crashid>
+   ceph crash rm <crashid>
 
 Remove a specific crash dump.
 
-::
+.. prompt:: bash #
 
-  ceph crash ls
+   ceph crash ls
 
 List the timestamp/uuid crashids for all new and archived crash info.
 
-::
+.. prompt:: bash #
 
-  ceph crash ls-new
+   ceph crash ls-new
 
 List the timestamp/uuid crashids for all newcrash info.
 
-::
+.. prompt:: bash #
 
-  ceph crash stat
+   ceph crash stat
 
 Show a summary of saved crash info grouped by age.
 
-::
+.. prompt:: bash #
 
-  ceph crash info <crashid>
+   ceph crash info <crashid>
 
 Show all details of a saved crash.
 
-::
+.. prompt:: bash #
 
    ceph crash prune <keep>
 
 Remove saved crashes older than 'keep' days.  <keep> must be an integer.
 
-::
+.. prompt:: bash #
 
    ceph crash archive <crashid>
 
 Archive a crash report so that it is no longer considered for the ``RECENT_CRASH`` health check and does not appear in the ``crash ls-new`` output (it will still appear in the ``crash ls`` output).
 
-::
+.. prompt:: bash #
 
    ceph crash archive-all