From 7c4a8b036dbe7e7c2f84381d2f6dc717716d9a1f Mon Sep 17 00:00:00 2001 From: postables Date: Tue, 7 Jul 2020 18:52:31 -0700 Subject: [PATCH 1/4] chore: start breathe integration --- cmake/FindPythonModule.cmake | 45 +++++++++++++++++++++++++++++ cmake/UseBreathe.cmake | 56 ++++++++++++++++++++++++++++++++++++ docs/conf.py | 21 +++++++++++++- 3 files changed, 121 insertions(+), 1 deletion(-) create mode 100644 cmake/FindPythonModule.cmake create mode 100644 cmake/UseBreathe.cmake diff --git a/cmake/FindPythonModule.cmake b/cmake/FindPythonModule.cmake new file mode 100644 index 0000000..16e0bc4 --- /dev/null +++ b/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() diff --git a/cmake/UseBreathe.cmake b/cmake/UseBreathe.cmake new file mode 100644 index 0000000..4936aac --- /dev/null +++ b/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() \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index aa4b113..b377600 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -153,4 +153,23 @@ texinfo_documents = [ (master_doc, 'c-template-REPLACEME', 'c-template-REPLACEME Documentation', author, 'c-template-REPLACEME', 'One line description of project.', 'Miscellaneous'), -] \ No newline at end of file +] + +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@') + From d6cf1351d3c853b419bf723a66396c5cf8fcd9be Mon Sep 17 00:00:00 2001 From: postables Date: Tue, 7 Jul 2020 19:20:21 -0700 Subject: [PATCH 2/4] fix cmake breathe usage --- CMakeLists.txt | 33 +++++++++++++++---- Makefile | 8 ++--- docs/code-reference/classes-and-functions.rst | 7 ++++ docs/code-reference/message.rst | 10 ++++++ docs/index.rst | 6 ++-- 5 files changed, 52 insertions(+), 12 deletions(-) create mode 100644 docs/code-reference/classes-and-functions.rst create mode 100644 docs/code-reference/message.rst diff --git a/CMakeLists.txt b/CMakeLists.txt index eaac97c..3a4c6cd 100644 --- a/CMakeLists.txt +++ b/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}") @@ -135,6 +137,25 @@ add_sphinx_doc( "HTML documentation" ) +add_breathe_doc( + SOURCE_DIR + ${CMAKE_CURRENT_SOURCE_DIR}/docs + BUILD_DIR + ${CMAKE_CURRENT_BINARY_DIR}/_build + CACHE_DIR + ${CMAKE_CURRENT_BINARY_DIR}/_doctrees + HTML_DIR + ${CMAKE_CURRENT_BINARY_DIR}/html + DOXY_FILE + ${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile.in + CONF_FILE + ${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py + TARGET_NAME + docs + COMMENT + "HTML documentation" +) + ############################# # END MACRO FUNCTION INVOKE # ############################# diff --git a/Makefile b/Makefile index 7752efa..9afa81a 100644 --- a/Makefile +++ b/Makefile @@ -1,19 +1,19 @@ .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: - (cd build ; cmake --build . --target doxygen-docs) + (cd build ; cmake -DPYTHON_EXECUTABLE=/usr/bin/python3 --build . --target doxygen-docs) .PHONY: sphinx-docs sphinx-docs: - (cd build ; cmake --build . --target sphinx-docs) + (cd build ; cmake -DPYTHON_EXECUTABLE=/usr/bin/python3 --build . --target sphinx-docs) .PHONY: valgrind-all-debug valgrind-all-debug: build-all-debug diff --git a/docs/code-reference/classes-and-functions.rst b/docs/code-reference/classes-and-functions.rst new file mode 100644 index 0000000..3b7fda0 --- /dev/null +++ b/docs/code-reference/classes-and-functions.rst @@ -0,0 +1,7 @@ +=============================== +Classes and functions reference +=============================== + +.. toctree:: + + message diff --git a/docs/code-reference/message.rst b/docs/code-reference/message.rst new file mode 100644 index 0000000..e23027f --- /dev/null +++ b/docs/code-reference/message.rst @@ -0,0 +1,10 @@ +Messaging classes +================= + +Message +------- +.. doxygenclass:: Message + :project: recipe-03 + :members: + :protected-members: + :private-members: diff --git a/docs/index.rst b/docs/index.rst index b24838f..cdb82f2 100644 --- a/docs/index.rst +++ b/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 From 1d72671c4d56354afae06acd2abd4aa37f5777c6 Mon Sep 17 00:00:00 2001 From: postables Date: Tue, 7 Jul 2020 19:29:55 -0700 Subject: [PATCH 3/4] chore: start updating configs --- CMakeLists.txt | 4 ++-- Makefile | 8 ++++++-- docs/Doxyfile.in | 2 +- docs/conf.py | 7 +++++-- 4 files changed, 14 insertions(+), 7 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 3a4c6cd..a9752fd 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -111,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 @@ -151,7 +151,7 @@ add_breathe_doc( CONF_FILE ${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py TARGET_NAME - docs + breathe-docs COMMENT "HTML documentation" ) diff --git a/Makefile b/Makefile index 9afa81a..7e65f9a 100644 --- a/Makefile +++ b/Makefile @@ -9,11 +9,15 @@ build-all-debug: .PHONY: doxygen-docs doxygen-docs: - (cd build ; cmake -DPYTHON_EXECUTABLE=/usr/bin/python3 --build . --target doxygen-docs) + (cd build ; cmake --build . --target doxygen-docs) .PHONY: sphinx-docs sphinx-docs: - (cd build ; cmake -DPYTHON_EXECUTABLE=/usr/bin/python3 --build . --target 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 diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 1389c4f..d3a9dba 100644 --- a/docs/Doxyfile.in +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index b377600..99789c9 100644 --- a/docs/conf.py +++ b/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 ------------------------------------------------ From 0bff3ce6945f0842f95eea3a8c0a1d22b12cb0fd Mon Sep 17 00:00:00 2001 From: postables Date: Tue, 7 Jul 2020 19:41:56 -0700 Subject: [PATCH 4/4] enable better building of sources --- .gitignore | 4 ++++ CMakeLists.txt | 22 +++++++++---------- Makefile | 3 +++ docs/code-reference/classes-and-functions.rst | 2 +- docs/code-reference/logger.rst | 14 ++++++++++++ docs/code-reference/message.rst | 10 --------- 6 files changed, 33 insertions(+), 22 deletions(-) create mode 100644 docs/code-reference/logger.rst delete mode 100644 docs/code-reference/message.rst diff --git a/.gitignore b/.gitignore index 03cc6d5..f74b27c 100644 --- a/.gitignore +++ b/.gitignore @@ -14,3 +14,7 @@ docs-build/ docs-sphinx/ _build/ + +_doctrees/ + +html/ diff --git a/CMakeLists.txt b/CMakeLists.txt index a9752fd..dbe9a83 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -122,15 +122,15 @@ 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 @@ -139,17 +139,17 @@ add_sphinx_doc( add_breathe_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}/html + ${PROJECT_SOURCE_DIR}/html DOXY_FILE - ${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile.in + ${PROJECT_SOURCE_DIR}/docs/Doxyfile.in CONF_FILE - ${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py + ${PROJECT_SOURCE_DIR}/docs/conf.py TARGET_NAME breathe-docs COMMENT diff --git a/Makefile b/Makefile index 7e65f9a..4016d92 100644 --- a/Makefile +++ b/Makefile @@ -27,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 # diff --git a/docs/code-reference/classes-and-functions.rst b/docs/code-reference/classes-and-functions.rst index 3b7fda0..37a8b05 100644 --- a/docs/code-reference/classes-and-functions.rst +++ b/docs/code-reference/classes-and-functions.rst @@ -4,4 +4,4 @@ Classes and functions reference .. toctree:: - message + logger diff --git a/docs/code-reference/logger.rst b/docs/code-reference/logger.rst new file mode 100644 index 0000000..a9df2bb --- /dev/null +++ b/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: \ No newline at end of file diff --git a/docs/code-reference/message.rst b/docs/code-reference/message.rst deleted file mode 100644 index e23027f..0000000 --- a/docs/code-reference/message.rst +++ /dev/null @@ -1,10 +0,0 @@ -Messaging classes -================= - -Message -------- -.. doxygenclass:: Message - :project: recipe-03 - :members: - :protected-members: - :private-members: