From 0fa568b54aad58b8f81e4f9702e83dbdbe2cc893 Mon Sep 17 00:00:00 2001 From: Kefu Chai Date: Tue, 4 May 2021 11:08:15 +0800 Subject: [PATCH 1/2] doc/man/8/cephfs-shell: reformat options * format global options using option directive * fix the header, so man/conf.py is able to parse the description * define "Synopsis" section to be consistent with other manpages. * drop reference to glossary using "term" as manapge does not have reference to glossary entries. Signed-off-by: Kefu Chai --- doc/cephfs/cephfs-shell.rst | 47 +++++++++++++++++++++++++++---------- 1 file changed, 35 insertions(+), 12 deletions(-) diff --git a/doc/cephfs/cephfs-shell.rst b/doc/cephfs/cephfs-shell.rst index 244d78bda12..62ebf60f205 100644 --- a/doc/cephfs/cephfs-shell.rst +++ b/doc/cephfs/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`` From 5191008aa4d3e7968139db848518d64084e5bf4d Mon Sep 17 00:00:00 2001 From: Kefu Chai Date: Tue, 4 May 2021 10:59:03 +0800 Subject: [PATCH 2/2] doc/man: build and install cephfs-shell manpage otherwise the manpage of cephfs-shell is not built and installed. Signed-off-by: Kefu Chai --- ceph.spec.in | 1 + debian/cephfs-shell.install | 1 + doc/cephfs/index.rst | 2 +- doc/man/8/CMakeLists.txt | 1 + doc/{cephfs => man/8}/cephfs-shell.rst | 0 doc/man_index.rst | 1 + 6 files changed, 5 insertions(+), 1 deletion(-) rename doc/{cephfs => man/8}/cephfs-shell.rst (100%) diff --git a/ceph.spec.in b/ceph.spec.in index 82295884696..39c3bade79f 100644 --- a/ceph.spec.in +++ b/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 diff --git a/debian/cephfs-shell.install b/debian/cephfs-shell.install index 4713a81b115..ee9e1399ff8 100644 --- a/debian/cephfs-shell.install +++ b/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 diff --git a/doc/cephfs/index.rst b/doc/cephfs/index.rst index 02ae3e9b293..b3de0f268aa 100644 --- a/doc/cephfs/index.rst +++ b/doc/cephfs/index.rst @@ -115,7 +115,7 @@ Mounting CephFS Mount CephFS using Kernel Driver Mount CephFS using FUSE Mount CephFS on Windows - Use the CephFS Shell + Use the CephFS Shell <../../man/8/cephfs-shell> Supported Features of Kernel Driver Manual: ceph-fuse <../../man/8/ceph-fuse> Manual: mount.ceph <../../man/8/mount.ceph> diff --git a/doc/man/8/CMakeLists.txt b/doc/man/8/CMakeLists.txt index 8e1b9373fc8..e020f347801 100644 --- a/doc/man/8/CMakeLists.txt +++ b/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 diff --git a/doc/cephfs/cephfs-shell.rst b/doc/man/8/cephfs-shell.rst similarity index 100% rename from doc/cephfs/cephfs-shell.rst rename to doc/man/8/cephfs-shell.rst diff --git a/doc/man_index.rst b/doc/man_index.rst index 30ab1c3eba7..d89cac2d310 100644 --- a/doc/man_index.rst +++ b/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