Skip to content
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.

Sign up for GitHub

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

Deprecate BUILD_DOCS: generate always the doc target but exclude from default make #434

Merged
merged 4 commits into from
Jul 29, 2024
Merged

Deprecate BUILD_DOCS: generate always the doc target but exclude from default make #434

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
42fc52d
Deprecate BUILD_DOCS: generate always the doc target but exclude it f…
j-rivero Jul 10, 2024
cd73d5c
Merge branch 'main' into jrivero/disable_doc_from_target_all
j-rivero Jul 22, 2024
3e138c2
Add a message for make doc if no doxygen is present
j-rivero Jul 23, 2024
da40bb0
Include migration notes
j-rivero Jul 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions Migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,14 @@ release will remove the deprecated code.
The change deprecates the HIDDEN_SYMBOLS_BY_DEFAULT flag that can be
removed.

1. **Breaking**: Now the code generates always a `doc` target that can be
called to generate the documentation. The `doc` target is excluded from
the ALL target so it needs to be explicitly triggered.

1. **Deprecated**: `BUILD_DOCS` CMake arguments is deprecated.
**Replacement**: building docs is excluded from the default build and needs
to be explicitly triggered by calling the `doc` target.

1. **Deprecated**: `GzPython.cmake`
**Replacement**: Use `find_package(Python3)` to find Python3 and the
`Python3_EXECUTABLE` variable instead of `PYTHON_EXECUTABLE`.
Expand Down
28 changes: 18 additions & 10 deletions cmake/GzCreateDocs.cmake
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,12 +42,6 @@
# "${GZ-<DESIGNATION>_DOXYGEN_TAGFILE} = ${GZ-<DESIGNATION>_API_URL}"
function(gz_create_docs)

option(BUILD_DOCS "Build docs" ON)
if (NOT ${BUILD_DOCS})
message(STATUS "Building Documentation disabled via BUILD_DOCS=OFF")
return()
endif()

#------------------------------------
# Define the expected arguments
set(options)
Expand Down Expand Up @@ -175,17 +169,31 @@ function(gz_create_docs)
configure_file(${GZ_CMAKE_DOXYGEN_DIR}/api.in
${CMAKE_BINARY_DIR}/api_tagfile.dox @ONLY)

add_custom_target(doc ALL
add_custom_target(doc
# Generate the API tagfile
${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/api_tagfile.dox
# Generate the API documentation
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/api.dox
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}

COMMENT "Generating API documentation with Doxygen" VERBATIM)

install(FILES ${CMAKE_BINARY_DIR}/${PROJECT_NAME_LOWER}.tag.xml
DESTINATION ${GZ_DATA_INSTALL_DIR})
add_custom_command(TARGET doc
POST_BUILD
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_BINARY_DIR}/${PROJECT_NAME_LOWER}.tag.xml ${GZ_DATA_INSTALL_DIR}
COMMENT "Install doxygen tag on doc target call")

if (DEFINED BUILD_DOCS)
message(DEPRECATION "The BUILD_DOCS option is now deprecated. For generating the"
"docs the 'doc' target can be called explicitly since its generated"
"unconditionally not including in the default build target.")
if (${BUILD_DOCS})
set_target_properties(doc PROPERTIES ALL ON)
endif()
endif()
else()
add_custom_target(doc
COMMAND ${CMAKE_COMMAND} -E echo "Need doxygen installation and api.in to generate documentation."
VERBATIM)
endif()

#--------------------------------------
Expand Down