Merge pull request ceph#4084 from ceph/wip-switch-to-breathe

Wip switch to breathe

Reviewed-by: Loic Dachary <[email protected]>

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

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

doc/conf.py

@@ -28,7 +28,7 @@
     '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)

doc/dev/documenting.rst

@@ -6,10 +6,10 @@ Code Documentation
 ==================
 
 C and C++ can be documented with Doxygen_, using the subset of Doxygen
-markup supported by Asphyxiate_.
+markup supported by Breathe_.
 
 .. _Doxygen: http://www.stack.nl/~dimitri/doxygen/
-.. _Asphyxiate: https://github.com/ceph/asphyxiate
+.. _Breathe: https://github.com/michaeljones/breathe
 
 The general format for function documentation is::
 

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

src/include/rados/librados.h

@@ -64,7 +64,6 @@ extern "C" {
  * Flags that can be set on a per-op basis via
  * rados_read_op_set_flags() and rados_write_op_set_flags().
  */
-/** @cond TODO_enums_not_yet_in_asphyxiate */
 enum {
   // fail a create operation if the object already exists
   LIBRADOS_OP_FLAG_EXCL               =  0x1,
@@ -96,7 +95,6 @@ enum {
  *
  * @{
  */
-/** @cond TODO_enums_not_yet_in_asphyxiate */
 enum {
 	LIBRADOS_CMPXATTR_OP_EQ  = 1,
 	LIBRADOS_CMPXATTR_OP_NE  = 2,
@@ -105,7 +103,6 @@ enum {
 	LIBRADOS_CMPXATTR_OP_LT  = 5,
 	LIBRADOS_CMPXATTR_OP_LTE = 6
 };
-/** @endcond */
 /** @} */
 
 /**
@@ -115,7 +112,6 @@ enum {
  * See librados.hpp for details.
  * @{
  */
-/** @cond TODO_enums_not_yet_in_asphyxiate */
 enum {
   LIBRADOS_OPERATION_NOFLAG             = 0,
   LIBRADOS_OPERATION_BALANCE_READS      = 1,
@@ -125,7 +121,6 @@ enum {
   LIBRADOS_OPERATION_SKIPRWLOCKS        = 16,
   LIBRADOS_OPERATION_IGNORE_OVERLAY     = 32,
 };
-/** @endcond */
 /** @} */
 
 /*