WIP Breathe Integration To Combine Sphinx And Doxygen

.gitignore

@@ -14,3 +14,7 @@ docs-build/
 docs-sphinx/
 
 _build/
+
+_doctrees/
+
+html/

CMakeLists.txt

@@ -23,9 +23,11 @@ list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
 # END CMAKE SETUP #
 ###################
 
-########################
-# BEGIN MACRO INCLUDES #
-########################
+##################
+# BEGIN INCLUDES #
+##################
+
+include(cmake/UseBreathe.cmake)
 
 include(cmake/FindSphinx.cmake)
 include(cmake/UseSphinxDoc.cmake)
@@ -64,9 +66,9 @@ include(cmake/logger_test.cmake)
 
 include(cmake/array_len_test.cmake)
 
-######################
-# END MACRO INCLUDES #
-######################
+################
+# END INCLUDES #
+################
 
 message(STATUS "Build type: ${CMAKE_BUILD_TYPE}")
 message(STATUS "Build flags: ${flags}")
@@ -109,7 +111,7 @@ define_array_len_test()
 
 add_doxygen_doc(
     BUILD_DIR
-        ${PROJECT_SOURCE_DIR}/build
+        ${PROJECT_SOURCE_DIR}/_build
     DOXY_FILE
         ${PROJECT_SOURCE_DIR}/docs/Doxyfile.in
     TARGET_NAME
@@ -120,21 +122,40 @@ add_doxygen_doc(
 
 add_sphinx_doc(
   SOURCE_DIR
-    ${CMAKE_CURRENT_SOURCE_DIR}/docs
+    ${PROJECT_SOURCE_DIR}/docs
   BUILD_DIR
-    ${CMAKE_CURRENT_BINARY_DIR}/_build
+    ${PROJECT_SOURCE_DIR}/_build
   CACHE_DIR
-    ${CMAKE_CURRENT_BINARY_DIR}/_doctrees
+    ${PROJECT_SOURCE_DIR}/_doctrees
   HTML_DIR
-    ${CMAKE_CURRENT_BINARY_DIR}/sphinx_html
+    ${PROJECT_SOURCE_DIR}/sphinx_html
   CONF_FILE
-    ${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py
+    ${PROJECT_SOURCE_DIR}/docs/conf.py
   TARGET_NAME
     sphinx-docs
   COMMENT
     "HTML documentation"
 )
 
+add_breathe_doc(
+  SOURCE_DIR
+    ${PROJECT_SOURCE_DIR}/docs
+  BUILD_DIR
+    ${PROJECT_SOURCE_DIR}/_build
+  CACHE_DIR
+    ${PROJECT_SOURCE_DIR}/_doctrees
+  HTML_DIR
+    ${PROJECT_SOURCE_DIR}/html
+  DOXY_FILE
+    ${PROJECT_SOURCE_DIR}/docs/Doxyfile.in
+  CONF_FILE
+    ${PROJECT_SOURCE_DIR}/docs/conf.py
+  TARGET_NAME
+    breathe-docs
+  COMMENT
+    "HTML documentation"
+)
+
 #############################
 # END MACRO FUNCTION INVOKE #
 #############################

Makefile

@@ -1,11 +1,11 @@
 .PHONY: build-all
 build-all:
-	( rm -rf build ; mkdir build ; cd build ; cmake -D CMAKE_C_COMPILER=gcc .. ; cmake -D CMAKE_C_COMPILER=gcc -build  . ; make )
+	( rm -rf build ; mkdir build ; cd build ; cmake -D CMAKE_C_COMPILER=gcc -DPYTHON_EXECUTABLE=/usr/bin/python3 .. ; cmake -D CMAKE_C_COMPILER=gcc -DPYTHON_EXECUTABLE=/usr/bin/python3 -build  . ; make )
 
 
 .PHONY: build-all-debug
 build-all-debug:
-	( rm -rf build ; mkdir build ; cd build ; cmake -D CMAKE_C_COMPILER=gcc -D CMAKE_BUILD_TYPE=Debug .. ; cmake -D CMAKE_C_COMPILER=gcc -D CMAKE_BUILD_TYPE=Debug -build  . ; make )
+	( rm -rf build ; mkdir build ; cd build ; cmake -D CMAKE_C_COMPILER=gcc -D CMAKE_BUILD_TYPE=Debug -DPYTHON_EXECUTABLE=/usr/bin/python3 .. ; cmake -D CMAKE_C_COMPILER=gcc -D CMAKE_BUILD_TYPE=Debug -DPYTHON_EXECUTABLE=/usr/bin/python3 -build  . ; make )
 
 .PHONY: doxygen-docs
 doxygen-docs:
@@ -15,6 +15,10 @@ doxygen-docs:
 sphinx-docs:
 	(cd build ; cmake --build . --target sphinx-docs)
 
+.PHONY: breathe-docs
+breathe-docs:
+	(cd build ; cmake --build . --target breathe-docs)
+
 .PHONY: valgrind-all-debug
 valgrind-all-debug: build-all-debug
 	bash ./scripts/valgrind.sh
@@ -23,6 +27,9 @@ valgrind-all-debug: build-all-debug
 valgrind-all: build-all
 	bash ./scripts/valgrind.sh
 
+.PHONY: clean
+clean:
+	rm -rf _doctrees build _build source html
 # Minimal makefile for Sphinx documentation
 #
 

cmake/FindPythonModule.cmake

@@ -0,0 +1,45 @@
+# Find a Python module
+# Found at http://www.cmake.org/pipermail/cmake/2011-January/041666.html
+# To use do: find_python_module(NumPy REQUIRED)
+# Reports also version of package, but you can't currently enforce a specific version to be
+# searched for...
+
+include(FindPackageHandleStandardArgs)
+function(find_python_module module)
+  # Fail if Python interpreter not known
+  if(NOT PYTHON_EXECUTABLE)
+    message(FATAL_ERROR "Use find_package(PythonInterp) first!")
+  endif()
+  string(TOLOWER ${module} _module_lower)
+  if(NOT ${_module_lower})
+    if(ARGC GREATER 1 AND ARGV1 STREQUAL "REQUIRED")
+      set(${module}_FIND_REQUIRED TRUE)
+    endif()
+    # Find module location
+    execute_process(
+      COMMAND
+        ${PYTHON_EXECUTABLE} "-c" "import re, ${_module_lower}; print(re.compile('/__init__.py.*').sub('',${_module_lower}.__file__))"
+      RESULT_VARIABLE _${module}_status
+      OUTPUT_VARIABLE _${module}_location
+      ERROR_QUIET
+      OUTPUT_STRIP_TRAILING_WHITESPACE
+      )
+    if(NOT _${module}_status)
+      set(${module} ${_${module}_location} CACHE STRING "Location of Python module ${module}")
+    endif()
+    # Find module version
+    execute_process(
+      COMMAND
+        ${PYTHON_EXECUTABLE} "-c" "import re, ${_module_lower}; print(re.compile('/__init__.py.*').sub('',${_module_lower}.__version__))"
+      OUTPUT_VARIABLE _${module}_ver
+      ERROR_QUIET
+      OUTPUT_STRIP_TRAILING_WHITESPACE
+      )
+  endif()
+
+  find_package_handle_standard_args(${module}
+    FOUND_VAR ${module}_FOUND
+    REQUIRED_VARS ${module}
+    VERSION_VAR _${module}_ver
+    )
+endfunction()

cmake/UseBreathe.cmake

@@ -0,0 +1,56 @@
+find_package(Doxygen REQUIRED)
+find_package(Perl REQUIRED)
+find_package(PythonInterp REQUIRED)
+find_package(Sphinx REQUIRED)
+include(FindPythonModule)
+find_python_module(breathe REQUIRED)
+
+function(add_breathe_doc)
+  set(options)
+  set(oneValueArgs
+    SOURCE_DIR
+    BUILD_DIR
+    CACHE_DIR
+    HTML_DIR
+    DOXY_FILE
+    CONF_FILE
+    TARGET_NAME
+    COMMENT
+    )
+  set(multiValueArgs)
+
+  cmake_parse_arguments(BREATHE_DOC
+    "${options}"
+    "${oneValueArgs}"
+    "${multiValueArgs}"
+    ${ARGN}
+    )
+
+  configure_file(
+    ${BREATHE_DOC_CONF_FILE}
+    ${BREATHE_DOC_BUILD_DIR}/conf.py
+    @ONLY
+    )
+
+  configure_file(
+    ${BREATHE_DOC_DOXY_FILE}
+    ${BREATHE_DOC_BUILD_DIR}/Doxyfile
+    @ONLY
+    )
+
+  add_custom_target(${BREATHE_DOC_TARGET_NAME}
+    COMMAND
+      ${SPHINX_EXECUTABLE}
+         -q
+         -b html
+         -c ${BREATHE_DOC_BUILD_DIR}
+         -d ${BREATHE_DOC_CACHE_DIR}
+         ${BREATHE_DOC_SOURCE_DIR}
+         ${BREATHE_DOC_HTML_DIR}
+    COMMENT
+      "Building ${BREATHE_DOC_TARGET_NAME} documentation with Breathe, Sphinx and Doxygen"
+    VERBATIM
+    )
+
+  message(STATUS "Added ${BREATHE_DOC_TARGET_NAME} [Breathe+Sphinx+Doxygen] target to build documentation")
+endfunction()

docs/Doxyfile.in

@@ -8,7 +8,7 @@ PROJECT_NAME           = c-template
 PROJECT_NUMBER         =
 PROJECT_BRIEF          =
 PROJECT_LOGO           =
-OUTPUT_DIRECTORY       = ../docs-build
+OUTPUT_DIRECTORY       =
 CREATE_SUBDIRS         = YES
 OUTPUT_LANGUAGE        = English
 BRIEF_MEMBER_DESC      = YES

docs/code-reference/classes-and-functions.rst

@@ -0,0 +1,7 @@
+===============================
+Classes and functions reference
+===============================
+
+.. toctree::
+
+   logger

docs/code-reference/logger.rst

@@ -0,0 +1,14 @@
+Logger classes
+=================
+
+Logger
+-------
+.. doxygenstruct:: thread_logger
+   :project: c-template-REPLACEME
+   :path: ...
+   :members:
+   :protected-members:
+   :private-members:
+   :undoc-members:
+   :outline:
+   :no-link:

docs/conf.py

@@ -17,8 +17,11 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
+
+import os
+import subprocess
+import sys
+
 # sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration ------------------------------------------------
@@ -153,4 +156,23 @@
 texinfo_documents = [
     (master_doc, 'c-template-REPLACEME', 'c-template-REPLACEME Documentation', author, 'c-template-REPLACEME',
      'One line description of project.', 'Miscellaneous'),
-]
+]
+
+breathe_projects = {'c-template-REPLACEME': '@BREATHE_DOC_BUILD_DIR@/xml'}
+
+
+def run_doxygen(folder):
+    """Run the doxygen make command in the designated folder"""
+
+    try:
+        retcode = subprocess.call("cd {}; doxygen".format(folder), shell=True)
+        if retcode < 0:
+            sys.stderr.write(
+                "doxygen terminated by signal {}".format(-retcode))
+    except OSError as e:
+        sys.stderr.write("doxygen execution failed: {}".format(e))
+
+
+def setup(app):
+    run_doxygen('@BREATHE_DOC_BUILD_DIR@')
+

docs/index.rst

@@ -1,15 +1,17 @@
-.. recipe-02 documentation master file, created by
+.. recipe-03 documentation master file, created by
    sphinx-quickstart on Thu Feb 15 17:02:41 2018.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to recipe-02's documentation!
+Welcome to recipe-03's documentation!
 =====================================
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+   code-reference/classes-and-functions
+
 
 
 Indices and tables