From 91c6c66fdd4fa89d76853d037fd5e98c3791b522 Mon Sep 17 00:00:00 2001 From: "Patrick M. Niedzielski" Date: Thu, 7 Nov 2024 10:52:45 -0500 Subject: [PATCH] Teach build system to build Doxygen docs This patch introduces three new targets to the build system when Doxygen is present: - `apidocs`: Build the public API documentation for public libbmq components. This target functions similarly to how the current `Doxyfile` builds documentation. - `internaldocs`: Build the internal documentation for all libbmq and libmqb components. The documentation built by this target is currently incomplete, and needs work along the lines of PRs #443 and #444. - `docs`: Build both the above documentation targets. This is a dependency of `make all`, so it will run by default. Signed-off-by: Patrick M. Niedzielski --- CMakeLists.txt | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) diff --git a/CMakeLists.txt b/CMakeLists.txt index b67307397..1ae475960 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -187,6 +187,103 @@ else() endif() endif() +find_package(Git) +if(GIT_FOUND) + execute_process( + COMMAND ${GIT_EXECUTABLE} describe HEAD + WORKING_DIRECTORY "${local_dir}" + OUTPUT_VARIABLE PROJECT_VERSION + ERROR_QUIET + OUTPUT_STRIP_TRAILING_WHITESPACE + ) +endif() + +# ----------------------------------------------------------------------------- +# DOCUMENTATION +# ----------------------------------------------------------------------------- + +find_package(Doxygen) +if(DOXYGEN_FOUND) + add_custom_target(docs + ALL + COMMENT "Build public and internal documentation" + ) + + # API Documentation for libbmq + + # Each CMake variable `DOXYGEN_something` becomes a Doxygen configuration + # named `something`. + set(DOXYGEN_ALIASES + "bbref{1}=@ref BloombergLP::\\1 \\\"\\1\\\"" + ) + set(DOXYGEN_EXTRACT_ALL YES) + set(DOXYGEN_EXTRACT_STATIC YES) + set(DOXYGEN_EXCLUDE_PATTERNS *.t.cpp *.cpp) + set(DOXYGEN_EXCLUDE_SYMBOLS + BloombergLP::bmqimp + BloombergLP::bmqp + BloombergLP::bslmt + BloombergLP::bmqst + ) + set(DOXYGEN_SHOW_INCLUDE_FILES NO) + set(DOXYGEN_SORT_MEMBER_DOCS NO) + set(DOXYGEN_PREDEFINED + "BSLS_KEYWORD_FINAL=final" + "BSLS_KEYWORD_DELETED=delete" + "BSLS_KEYWORD_OVERRIDE=override" + "BSLMF_NESTED_TRAIT_DECLARATION(..)=" + ) + set(DOXYGEN_EXPAND_AS_DEFINED + "BSLS_ASSERT_SAFE_IS_ACTIVE=1" + "BSLS_COMPILER_FEATURES_SUPPORT_GENERALIZED_INITIALIZERS" + "BSLS_LIBRARYFEATURES_HAS_CPP17_BASELINE_LIBRARY" + "BSLS_LIBRARYFEATURES_HAS_CPP11_UNIQUE_PTR" + ) + set(DOXYGEN_SHOW_NAMESPACES NO) + set(DOXYGEN_REPEAT_BRIEF YES) + set(DOXYGEN_INLINE_INHERITED_MEMB YES) + set(DOXYGEN_STRIP_FROM_PATH src/groups/bmq) + set(DOXYGEN_OUTPUT_DIRECTORY apidocs) + set(DOXYGEN_IMAGE_PATH docs/assets/images) + set(DOXYGEN_PROJECT_ICON docs/favicon.ico) + set(DOXYGEN_PROJECT_LOGO docs/assets/images/blazingmq_logo.svg) + set(DOXYGEN_PROJECT_NAME libbmq) + set(DOXYGEN_PROJECT_BRIEF + "C++ SDK for BlazingMQ clients and plugins" + ) + set(DOXYGEN_USE_MDFILE_AS_MAINPAGE ./README.md) + set(DOXYGEN_REFERENCED_BY_RELATION YES) + set(DOXYGEN_REFERENCES YES) + set(DOXYGEN_ALPHABETICAL_INDEX NO) + set(DOXYGEN_FULL_SIDEBAR YES) + set(DOXYGEN_GENERATE_TREEVIEW YES) + doxygen_add_docs( + apidocs + src/groups/bmq/bmqa + src/groups/bmq/bmqt + src/groups/bmq/bmqpi + README.md + COMMENT "Generate public Doxygen documentation for libbmq" + ) + add_dependencies(docs apidocs) + + # Internal documentation for both libbmq and libmqb. + + unset(DOXYGEN_EXCLUDE_SYMBOLS) + set(DOXYGEN_EXTRACT_PRIVATE YES) + set(DOXYGEN_SHOW_INCLUDE_FILES YES) + set(DOXYGEN_SHOW_NAMESPACES YES) + set(DOXYGEN_GENERATE_TODOLIST YES) + set(DOXYGEN_STRIP_FROM_PATH src/groups) + set(DOXYGEN_OUTPUT_DIRECTORY internaldocs) + doxygen_add_docs( + internaldocs + src/groups/ + COMMENT "Generate internal Doxygen documentation for libbmq and libmqb" + ) + add_dependencies(docs internaldocs) +endif() + # ----------------------------------------------------------------------------- # PROJECTS # -----------------------------------------------------------------------------