Bug #24800
Updated by Nathan Cutler almost 6 years ago
With older versions of Sphinx (looks like 1.2 and earlier), the rendering of the ".. option" directive is suboptimal.
As of (at least) Sphinx 1.3.6 the problem does not occur. But CentOS 7 has Sphinx 1.1.3.
The problem:
When rendering the source file @doc/man/8/ceph-bluestore-tool.rst@ into @/usr/share/man/man8/ceph-bluestore-tool.8@, the lines
<pre>.. option:: bluefs-export
Export the contents of BlueFS (i.e., rocksdb files) to an output directory.
</pre>
get rendered as:
<pre>.B \-export
Export the contents of BlueFS (i.e., rocksdb files) to an output directory.
</pre>
Somehow the string before the first hyphen ("bluefs" in this case) is getting lost.
I have verified this by examining the following files:
http://download.ceph.com/rpm-mimic/el7/x86_64/ceph-osd-13.2.0-0.el7.x86_64.rpm
http://download.ceph.com/rpm-luminous/el7/x86_64/ceph-mon-12.2.5-0.el7.x86_64.rpm
and I have also reproduced in a CentOS 7 Docker container by doing the following:
<pre>./install-deps.sh
./do_cmake.sh -DWITH_MANPAGE=ON
cd build
make manpages
</pre>
and examining the resulting file @./doc/man/ceph-bluestore-tool.8@
Within the corpus of Ceph manpages, there are several that contain lists of subcommands. In some manpages the subcommands are marked up using ".. option", while in others the ":command:" syntax is used.
It is true that this issue is not reproducible with newer versions of Sphinx, and thus can be expected to "go away eventually". On the other hand, eventually", it is affecting our users now and in any case anyway it's desirable to use consistent markup for subcommands throughout all the Ceph manpages.