doc: fix doc build

[tchaikov]

http://tracker.ceph.com/issues/12180

see http://gitbuilder.sepia.ceph.com/gitbuilder-doc/log.cgi?log=53a2143eb7e549de1185b01ed0bde841ffa5235a

Running Sphinx v1.1.3
Exception occurred:
File "/srv/autobuild-ceph/gitbuilder.git/build/doc/conf.py", line 56, in _get_manpages
assert one == three
AssertionError
The full traceback has been saved in /tmp/sphinx-err-mXeenl.log, if you want to report the issue to the developers.

[loic-bot]

SUCCESS: http://jenkins.ceph.dachary.org/job/ceph/6147/

• SUCCESS http://jenkins.ceph.dachary.org/job/ceph/LABELS=centos-7&&x86_64/6147/
• SUCCESS http://jenkins.ceph.dachary.org/job/ceph/LABELS=ubuntu-14.04&&x86_64/6147/

[ghost]

Reviewed-by: Loic Dachary <ldachary@redhat.com>

as soon as the doc gitbuilder is happy with the change.

[ghost]

@tchaikov is there an issue associated with this bug ?

[tchaikov]

@dachary i searched but failed to find any. shall i file one ?

[tchaikov]

http://gitbuilder.sepia.ceph.com/gitbuilder-doc/#origin/wip-fix-doc-hammer looks yellow =)

[ghost]

@tchaikov for backporting it helps to be strict and have a 1 to 1 correspondance between pull requests and issues. Could you add a reference to the commit that fixes this issue in master ? Or a short explanation about why it does not need fixing in master. With that I'll create the necessary issues.

[tchaikov]

@dachary i will keep it in my mind next time.

there are a bunch of commits that fix this issue: see #4291

the reason why we don't need this fix in master:

in hammer, librados.h skips the enum definitions when doxygen is processing all header files if not blacklisted in Doxyfile. but one @cond does not have its corresponding @endcond directive. and asphyxiate is not able to handle it. the files under src/tracing emit var sections in the doxygen generated XML files, again asphyxiate is not able to render the var sections into sphinx file.
in master, we are using breathe to render the doxygen generated. unlike asphyxiate, breathe is able to render the enum and some other sections. so we don't need to skip the enum definitions and disable the "src/tracing" in Doxyfile. moreover, we only render the only 2 source files referenced by our document which does not include the files under src/tracing.