Bug #24800

Updated by Nathan Cutler almost 2 years ago

With older versions of Sphinx (looks like 1.2 and earlier), the rendering of the ".. option" directive The process we use to generate man pages from *.rst source files is suboptimal. possibly buggy.

As of (at least) Sphinx 1.3.6 For example, the problem does not occur. But CentOS 7 has Sphinx 1.1.3.

The problem:

When rendering
build process transforms the source file @doc/man/8/ceph-bluestore-tool.rst@ from the source repo into @/usr/share/man/man8/ceph-bluestore-tool.8@, the lines @/usr/share/man/man8/ceph-bluestore-tool.8.gz@ and it is this latter file that gets installed on users' systems.

The former file has, e.g.:

<pre>.. option:: bluefs-export

Export the contents of BlueFS (i.e., rocksdb files) to an output directory.

get rendered as: In the latter, this becomes:

<pre>.B \-export
Export the contents of BlueFS (i.e., rocksdb files) to an output directory.

Somehow the string before the first hyphen ("bluefs" in this case) is getting lost.

I have verified this by examining the following files:

and I have also reproduced in a CentOS 7 Docker container by doing not yet looked at the following:

cd build
make manpages

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
deb packages to "go away eventually", it is affecting our users now and anyway it's desirable to use consistent markup for subcommands throughout all see if they have the Ceph manpages. same problem.