Project

General

Profile

Bug #24800

ceph-bluestore-tool manpage not getting rendered correctly

Added by Nathan Cutler 12 months ago. Updated 11 months ago.

Status:
Resolved
Priority:
Normal
Assignee:
Category:
-
Target version:
-
Start date:
07/06/2018
Due date:
% Done:

0%

Source:
Tags:
Backport:
mimic,luminous
Regression:
No
Severity:
3 - minor
Reviewed:
Affected Versions:
ceph-qa-suite:
Pull request ID:

Description

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

.. option:: bluefs-export

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

get rendered as:

.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:

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:

./install-deps.sh
./do_cmake.sh -DWITH_MANPAGE=ON
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.

The ".. option" directive works for subcommands as long as they do not contain hyphens. See, for example "man ceph-dencoder".

Since the issue is not reproducible with newer versions of Sphinx, and thus can be expected to "go away eventually", it makes sense to merge a minimal fix - i.e. convert subcommand markup from "..option" to ":command:" but only in those manpages that have subcommands containing hyphens.


Related issues

Copied to Ceph - Backport #25062: mimic: ceph-bluestore-tool manpage not getting rendered correctly Resolved
Copied to Ceph - Backport #25063: luminous: ceph-bluestore-tool manpage not getting rendered correctly Resolved

History

#1 Updated by Nathan Cutler 11 months ago

  • Status changed from New to In Progress
  • Assignee set to Nathan Cutler

Looking at http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#option-lists I see what the problem is. In reStructuredText, option is designed for options that start with a hyphen -. So rST is just ignoring the characters that precede the first hyphen.

#2 Updated by Nathan Cutler 11 months ago

Will need to check rendering for all instances, as per ag '\.\. option'

#3 Updated by Nathan Cutler 11 months ago

Interestingly enough, the bug does not show up in the HTML version: http://docs.ceph.com/docs/master/man/8/ceph-bluestore-tool/

#4 Updated by Nathan Cutler 11 months ago

The plot thickens. I can build the manpages by doing "./do_cmake.sh -DWITH_MANPAGE=ON ; cd build ; make manpages" but the resulting file ./doc/man/ceph-bluestore-tool.8 does not exhibit the bug.

Tried this in openSUSE Leap 42.3 with Sphinx 1.3.6 and in openSUSE Leap 15.0 with Sphinx 1.6.5.

Also, the ceph-bluestore-tool manpage in the ceph-osd (12.2.5) package that ships with Leap 42.3 does not exhibit the bug.

So, the bug is reproducible only in certain environments.

#5 Updated by Nathan Cutler 11 months ago

Reproduced in CentOS 7, Sphinx 1.1.3

#6 Updated by Nathan Cutler 11 months ago

  • Description updated (diff)

#7 Updated by Nathan Cutler 11 months ago

  • Description updated (diff)

#8 Updated by Nathan Cutler 11 months ago

  • Description updated (diff)

#9 Updated by Nathan Cutler 11 months ago

  • Status changed from In Progress to Need Review

#10 Updated by Nathan Cutler 11 months ago

  • Backport set to mimic,luminous

#11 Updated by Nathan Cutler 11 months ago

  • Status changed from Need Review to Pending Backport

#12 Updated by Nathan Cutler 11 months ago

  • Copied to Backport #25062: mimic: ceph-bluestore-tool manpage not getting rendered correctly added

#13 Updated by Nathan Cutler 11 months ago

  • Copied to Backport #25063: luminous: ceph-bluestore-tool manpage not getting rendered correctly added

#14 Updated by Nathan Cutler 11 months ago

  • Subject changed from RestructuredText man pages are not getting rendered correctly to ceph-bluestore-tool manpage not getting rendered correctly

#15 Updated by Nathan Cutler 11 months ago

  • Status changed from Pending Backport to Resolved

Also available in: Atom PDF