doc: Switch doxygen integration back to breathe

* asphyxiate needs more toolings, see
  https://github.com/ceph/asphyxiate/issues/1
* this commit basically reverts c96064
* use `autodoxygen` directive to doxygen referenced source files
* do not call `doxygen` explicitly in `build-doc`, `autodoxygen`
  will take care of it.

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

diff --git a/admin/build-doc b/admin/build-doc
index dfbd5e45f0f6603787e5c80bea45047e779d5051..f3ebd3402e39bedb3297bd379e19ac0e5383a76b 100755 (executable)
--- a/admin/build-doc
+++ b/admin/build-doc
@@ -47,10 +47,6 @@ else
     fi
 fi
 
-if [ ! -e build-doc/doxygen/xml ]; then
-    doxygen
-fi
-
 cat src/osd/PG.h src/osd/PG.cc | doc/scripts/gen_state_diagram.py > doc/dev/peering_graph.generated.dot
 
 cd build-doc

diff --git a/admin/doc-requirements.txt b/admin/doc-requirements.txt
index ce4654c660007ad0cbeae0f0d960f8a82bb495b9..aba92c28bef9dca9b9b9b17996dfff3ed94a568e 100644 (file)
--- a/admin/doc-requirements.txt
+++ b/admin/doc-requirements.txt
@@ -1,3 +1,3 @@
 Sphinx == 1.1.3
 -e git+https://github.com/ceph/sphinx-ditaa.git#egg=sphinx-ditaa
--e git+https://github.com/ceph/asphyxiate.git#egg=asphyxiate
+-e git+https://github.com/michaeljones/breathe#egg=breathe

diff --git a/doc/conf.py b/doc/conf.py
index 98ce7d861b3a64a2aa5b75ccbed919f7f72f9da8..99c66ed38493644168f8143d2a4b96aa82b0f487 100644 (file)
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -28,7 +28,7 @@ extensions = [
     'sphinx.ext.graphviz',
     'sphinx.ext.todo',
     'sphinx_ditaa',
-    'asphyxiate',
+    'breathe',
     ]
 todo_include_todos = True
 
@@ -69,14 +69,21 @@ def _get_manpages():
 
 man_pages = list(_get_manpages())
 
-asphyxiate_doxygen_xml = 'doxygen'
-
 top_level = os.path.dirname(
     os.path.dirname(
         os.path.abspath(__file__)
     )
 )
 
+breathe_default_project = "Ceph"
+# see $(top_srcdir)/Doxyfile
+
+breathe_build_directory = os.path.join(top_level, "build-doc")
+breathe_projects = {"Ceph": os.path.join(top_level, breathe_build_directory)}
+breathe_projects_source = {
+    "Ceph": (os.path.join(top_level, "src/include/rados"),
+             ["rados_types.h", "librados.h"])
+}
 pybind = os.path.join(top_level, 'src/pybind')
 if pybind not in sys.path:
     sys.path.insert(0, pybind)

diff --git a/doc/rados/api/librados.rst b/doc/rados/api/librados.rst
index 5c3742fc8064515d517f302fa4d8ebbb781ea692..483ef8e67764c8ab5ed0fcf0a49c3db92385d9df 100644 (file)
--- a/doc/rados/api/librados.rst
+++ b/doc/rados/api/librados.rst
@@ -183,5 +183,5 @@ Note that all the :c:type:`rados_completion_t` must be freed with :c:func:`rados
 API calls
 =========
 
- .. doxygenfile:: rados_types.h
- .. doxygenfile:: librados.h
+ .. autodoxygenfile:: rados_types.h
+ .. autodoxygenfile:: librados.h