Merge PR #41134 into master

* refs/pull/41134/head:
	doc/man: build and install cephfs-shell manpage
	doc/man/8/cephfs-shell: reformat options

Reviewed-by: Patrick Donnelly <pdonnell@redhat.com>

ceph.spec.in

@@ -2317,6 +2317,7 @@ fi
 %files -n cephfs-shell
 %{python3_sitelib}/cephfs_shell-*.egg-info
 %{_bindir}/cephfs-shell
+%{_mandir}/man8/cephfs-shell.8*
 %endif
 
 %files -n cephfs-top

debian/cephfs-shell.install

@@ -1,2 +1,3 @@
 usr/bin/cephfs-shell
 usr/lib/python3*/dist-packages/cephfs_shell-*.egg-info
+usr/share/man/man8/cephfs-shell.8

doc/cephfs/index.rst

@@ -115,7 +115,7 @@ Mounting CephFS
     Mount CephFS using Kernel Driver <mount-using-kernel-driver>
     Mount CephFS using FUSE <mount-using-fuse>
     Mount CephFS on Windows <ceph-dokan>
-    Use the CephFS Shell <cephfs-shell>
+    Use the CephFS Shell <../../man/8/cephfs-shell>
     Supported Features of Kernel Driver <kernel-features>
     Manual: ceph-fuse <../../man/8/ceph-fuse>
     Manual: mount.ceph <../../man/8/mount.ceph>

doc/man/8/CMakeLists.txt

@@ -38,6 +38,7 @@ list(APPEND man_srcs
   ${osd_srcs}
   ${mon_srcs}
   ceph-mds.rst
+  cephfs-shell.rst
   cephfs-top.rst
   librados-config.rst
   cephadm.rst

doc/man/8/cephfs-shell.rst

@@ -1,10 +1,22 @@
+:orphan:
 
-=============
-CephFS Shell
-=============
+===================================================
+cephfs-shell -- Shell-like tool talking with CephFS
+===================================================
+
+.. program:: cephfs-shell
+
+Synopsis
+========
+
+| **cephfs-shell** [options] [command]
+| **cephfs-shell** [options] -- [command, command,...]
+
+Description
+===========
 
 CephFS Shell provides shell-like commands that directly interact with the
-:term:`Ceph File System`.
+Ceph File System.
 
 This tool can be used in interactive mode as well as in non-interactive mode.
 In former mode, cephfs-shell opens a shell session and after the given command
@@ -17,16 +29,20 @@ return value.
 Behaviour of CephFS Shell can be tweaked using ``cephfs-shell.conf``. Refer to
 `CephFS Shell Configuration File`_ for details.
 
-Usage :
+Options
+=======
 
-    cephfs-shell [options] [command]
-    cephfs-shell [options] -- [command, command,...]
+.. option:: -c, --config FILE
 
-Options :
-    -c, --config FILE     Path to cephfs-shell.conf
-    -b, --batch FILE      Path to batch file.
-    -t, --test FILE       Path to transcript(s) in FILE for testing
+   Path to cephfs-shell.conf
 
+.. option:: -b, --batch FILE
+
+   Path to batch file.
+
+.. option:: -t, --test FILE
+
+   Path to transcript(s) in FILE for testing
 
 .. note::
 
@@ -516,7 +532,9 @@ Right now, CephFS Shell inherits all its options from its dependency ``cmd2``.
 Therefore, these options might vary with the version of ``cmd2`` installed on
 your system. Refer to ``cmd2`` docs for a description of these options.
 
-Following is a sample ``cephfs-shell.conf``::
+Following is a sample ``cephfs-shell.conf``
+
+.. code-block:: ini
 
     [cephfs-shell]
     prompt = CephFS:~/>>>
@@ -586,3 +604,8 @@ Following exit codes are returned by cephfs shell
 +-----------------------------------------------+-----------+
 | Interrupted function call                     |     22    |
 +-----------------------------------------------+-----------+
+
+Files
+=====
+
+``~/.cephfs-shell.conf``

doc/man_index.rst

@@ -25,6 +25,7 @@
    man/8/cephadm
    man/8/cephfs-top
    man/8/cephfs-mirror
+   man/8/cephfs-shell
    man/8/crushtool
    man/8/librados-config
    man/8/monmaptool