-
Notifications
You must be signed in to change notification settings - Fork 71
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add application-help-to-doxygen #533
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -25,6 +25,10 @@ | |
# * ${PROJECT_NAME}_VERSION_(MINOR|MAJOR) The project's major/minor version, | ||
# generally set by the project() command in the top-level CMakeLists.txt. | ||
# | ||
# Input Global Properties | ||
# * ${PROJECT_NAME}_HELP a list of doxygen page anchors to add to the | ||
# "Application Help" page | ||
# | ||
# Optional project information | ||
# Output to a metadata file for html index page generation by Jekyll | ||
# * ${UPPER_PROJECT_NAME}_DESCRIPTION A short description of the project | ||
|
@@ -88,6 +92,20 @@ if(NOT COMMON_ORGANIZATION_NAME) | |
set(COMMON_ORGANIZATION_NAME Unknown) | ||
endif() | ||
|
||
# collect application help page | ||
get_property(__help GLOBAL PROPERTY ${PROJECT_NAME}_HELP) | ||
if(__help) | ||
list(APPEND DOXYGEN_EXTRA_INPUT ${PROJECT_BINARY_DIR}/help) | ||
set(__index "${PROJECT_BINARY_DIR}/help/applications.md") | ||
file(WRITE ${__index} "Application Help {#apps} | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Applications in plural ? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Afaik that is frenglish. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. OK, my bad then :-) |
||
============ | ||
|
||
") | ||
foreach(_help ${__help}) | ||
file(APPEND ${__index} "* @subpage ${_help}\n") | ||
endforeach() | ||
endif() | ||
|
||
# list-to-string transform | ||
string(REPLACE ";" " " DOXYGEN_EXTRA_INPUT "${DOXYGEN_EXTRA_INPUT}") | ||
|
||
|
@@ -114,6 +132,9 @@ set_target_properties(${PROJECT_NAME}-doxygen PROPERTIES | |
if(TARGET ${PROJECT_NAME}-coverage) # CoverageReport generated by "tests" in this case | ||
add_dependencies(${PROJECT_NAME}-doxygen ${PROJECT_NAME}-coverage) | ||
endif() | ||
if(TARGET ${PROJECT_NAME}-help) | ||
add_dependencies(${PROJECT_NAME}-doxygen ${PROJECT_NAME}-help) | ||
endif() | ||
|
||
if(NOT TARGET doxygen) | ||
add_custom_target(doxygen) | ||
|
@@ -200,7 +221,6 @@ set_target_properties(${PROJECT_NAME}-doxycopy PROPERTIES | |
|
||
if(NOT TARGET doxycopy) | ||
add_custom_target(doxycopy) | ||
set_target_properties(doxycopy PROPERTIES | ||
EXCLUDE_FROM_DEFAULT_BUILD ON) | ||
set_target_properties(doxycopy PROPERTIES EXCLUDE_FROM_DEFAULT_BUILD ON) | ||
endif() | ||
add_dependencies(doxycopy ${PROJECT_NAME}-doxycopy) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How about file(GLOB __help "${PROJECT_BINARY_DIR}/help/*.md") instead of a global property? Potentially a bit more flexible and decoupled (for someone who wants to add his own help files in there).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No, it would pick up stale files (see above for manual checks during release...)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The release is made by a Jenkin plan which does a clean build, and anyone doing a manual release will (should) do the same... But I see your point, as you prefer. ${PROJECT_NAME}_HELP should be documented as an IN variable here for consistency, and as an OUT variable in CommonApplication.cmake normally.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do we document this if the user is not supposed to use them?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's a fair question. My take on this is to try to document every in/out variable of each CMake file, because it makes the interdependence between different files explicit. Having hidden global variables is not good for maintenance in the long run. Regarding this specific case, I am not sure if there is a reason users should be discouraged to add their own help file for a python application for instance (tide, rtneuron-app.py, ...)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
done