diff --git a/CMakeLists.txt b/CMakeLists.txt index bfa2f191d2..858e44b144 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -123,3 +123,33 @@ add_subdirectory(geo_lookup) add_subdirectory(l1) add_subdirectory(tecs) add_subdirectory(validation) + +#============================================================================= +# Doxygen +# +option(BUILD_DOXYGEN "Build doxygen documentation" OFF) + +if (BUILD_DOXYGEN) + find_package(Doxygen) + if (DOXYGEN_FOUND) + # set input and output files + set(DOXYGEN_IN ${CMAKE_SOURCE_DIR}/docs/Doxyfile.in) + set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile) + + # request to configure the file + configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY) + + # note the option ALL which allows to build the docs together with the application + add_custom_target(doxygen ALL + COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT} + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} + COMMENT "Generating documentation with Doxygen" + DEPENDS + VERBATIM + USES_TERMINAL + ) + + else() + message(FATAL_ERROR "Doxygen needs to be installed to generate documentation") + endif() +endif() diff --git a/Jenkinsfile b/Jenkinsfile index 165d6c3c77..6fbd0346a8 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -106,6 +106,33 @@ pipeline { } } + stage('doxygen') { + agent { + docker { + image 'px4io/px4-dev-base:2018-03-30' + args '-v ${CCACHE_DIR}:${CCACHE_DIR}:rw' + } + } + steps { + sh 'export' + sh 'ccache -z' + sh 'make distclean' + //sh 'make doxygen' + sh 'ccache -s' + // publish html + publishHTML target: [ + reportTitles: 'Doxygen', + allowMissing: true, + alwaysLinkToLastBuild: true, + keepAll: true, + reportDir: 'build/doxygen/Documentation', + reportFiles: '*', + reportName: 'doxygen' + ] + sh 'make distclean' + } + } + } // parallel } diff --git a/Makefile b/Makefile index 97e0e54aba..947fe823d2 100644 --- a/Makefile +++ b/Makefile @@ -86,6 +86,12 @@ endef all: @$(call cmake-build,$@,$(SRC_DIR)) +# Documentation +# -------------------------------------------------------------------- +doxygen: + @$(call cmake-build,$@,$(SRC_DIR), "-DBUILD_DOXYGEN=ON") + @cmake --build $(SRC_DIR)/build/doxygen --target doxygen + # Testing # -------------------------------------------------------------------- diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in new file mode 100644 index 0000000000..87413e35ef --- /dev/null +++ b/docs/Doxyfile.in @@ -0,0 +1,121 @@ +# Use: `doxygen -g test.txt` to generate all possible settings for this file + +# For modern doxygen style uncomment these three lines: + #HTML_EXTRA_STYLESHEET = @CMAKE_CURRENT_SOURCE_DIR@/doxygen/customdoxygen.css + #HTML_HEADER = @CMAKE_SOURCE_DIR@/Documentation/header.html + #HTML_FOOTER = @CMAKE_SOURCE_DIR@/Documentation/footer.html + +# not interested build output +QUIET = YES + +# Basic settings: +PROJECT_NAME = "@CMAKE_PROJECT_NAME@" +PROJECT_NUMBER = @PROJECT_VERSION_MAJOR@.@PROJECT_VERSION_MINOR@.@PROJECT_VERSION_PATCH@@VERSION_TYPE@ +STRIP_FROM_PATH = @CMAKE_SOURCE_DIR@ + +INPUT = @CMAKE_SOURCE_DIR@/README.md \ + @CMAKE_SOURCE_DIR@ \ + @CMAKE_SOURCE_DIR@/src \ + @CMAKE_BINARY_DIR@/ \ + @CMAKE_BINARY_DIR@/uORB + +FILE_PATTERNS = *.h \ + *.hpp \ + *.hh \ + *.c \ + *.cc \ + *.cpp.in \ + *.cpp \ + *.md + +RECURSIVE = YES +USE_MDFILE_AS_MAINPAGE = "@CMAKE_SOURCE_DIR@/README.md" +# output location +HTML_OUTPUT = "@CMAKE_BINARY_DIR@/Documentation" + +IMAGE_PATH = "@CMAKE_SOURCE_DIR@" + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, +# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), +# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, +# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), +# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, +# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, +# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, +# Ukrainian and Vietnamese. +# The default value is: English. +OUTPUT_LANGUAGE = English + +# Color style +HTML_COLORSTYLE_HUE = 220 +HTML_COLORSTYLE_SAT = 40 +HTML_COLORSTYLE_GAMMA = 80 + +# max size 200x55px +PROJECT_LOGO = + + +# If the REFERENCED_BY_RELATION tag is set to YES then for each documented +# function all documented functions referencing it will be listed. +# The default value is: NO. +REFERENCED_BY_RELATION = YES + +# If the REFERENCES_RELATION tag is set to YES then for each documented function +# all documented entities called/used by that function will be listed. +# The default value is: NO. +REFERENCES_RELATION = YES + +# This is nice to have - callgraphs of functions +HAVE_DOT = YES +CALL_GRAPH = YES +CALLER_GRAPH = YES + +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +GENERATE_LEGEND = YES +INCLUDED_BY_GRAPH = YES +INCLUDE_GRAPH = YES +DOT_IMAGE_FORMAT = svg +INTERACTIVE_SVG = YES + +# More insight to templates, generaly not needed +TEMPLATE_RELATIONS = NO + +# in class diagrams, you will have members and such +# Also they will be bigger +UML_LOOK = YES +UML_LIMIT_NUM_FIELDS = 6 + +# should all pictures be collapsed? +HTML_DYNAMIC_SECTIONS = NO + + +# use with: /// @todo Do more stuff. +GENERATE_TODOLIST = YES + +# we want all we can get +EXTRACT_ALL = YES +EXTRACT_STATIC = YES +EXTRACT_PRIVATE = YES + +# We do not need latex output +GENERATE_LATEX = NO +USE_PDFLATEX = NO + +# this makes first sentence from comment block a brief description. +# It is VERY useful +JAVADOC_AUTOBRIEF = YES + +# Why not... +BUILTIN_STL_SUPPORT = YES + +# Do we want source code browser? YES! Do we want strip comments? NO +SOURCE_BROWSER = YES +STRIP_CODE_COMMENTS = NO + +# Side panel +# If you enable this, change .container max-width: 960px; to 1240px +GENERATE_TREEVIEW = YES