New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: fix doc build #5095

Merged
merged 3 commits into from Jun 27, 2015

Conversation

Projects
None yet
2 participants
@tchaikov
Contributor

tchaikov commented Jun 27, 2015

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.

tchaikov added some commits Jun 27, 2015

doc: let doxygen ignore src/tracing
Signed-off-by: Kefu Chai <kchai@redhat.com>
doc: remove orphan: directive in ceph-create-keys.rst
* it is used to silence the sphinx warning, but conf.py
  does not like it.

Signed-off-by: Kefu Chai <kchai@redhat.com>
doc: add the corresponding @endcond command for @cond
* they are used to applease asphyxiate, as it
  is not able to handle "enum" sections

Signed-off-by: Kefu Chai <kchai@redhat.com>

@tchaikov tchaikov added this to the hammer milestone Jun 27, 2015

@ghost

This comment has been minimized.

ghost commented Jun 27, 2015

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

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

@ghost

This comment has been minimized.

ghost commented Jun 27, 2015

@tchaikov is there an issue associated with this bug ?

@tchaikov

This comment has been minimized.

Contributor

tchaikov commented Jun 27, 2015

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

@tchaikov

This comment has been minimized.

Contributor

tchaikov commented Jun 27, 2015

tchaikov added a commit that referenced this pull request Jun 27, 2015

Merge pull request #5095 from ceph/wip-fix-doc-hammer
doc: fix doc build

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

@tchaikov tchaikov merged commit 59f37a9 into hammer Jun 27, 2015

@tchaikov tchaikov deleted the wip-fix-doc-hammer branch Jun 27, 2015

@ghost

This comment has been minimized.

ghost commented Jun 27, 2015

@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

This comment has been minimized.

Contributor

tchaikov commented Jun 27, 2015

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment