niklas/cyclonedds
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix and simplify building docs and schemas (#441)

Browse source 
Fix and simplify building docs and schemas

1. Do an in-source build of derived schemas instead of building into build and checking that the files match.
2. Fix paths of installed docs, which were failing on me
3. Consolidate docs into same cmakelists that generates schema files
4. Trang is usually available as an executable, so find it with find_program.
5. Add doc dependencies to package.xml

Signed-off-by: Dan Rose <dan@digilabs.io>
This commit is contained in:
Dan Rose 2020-04-02 10:25:16 -05:00 • committed by GitHub
parent 9207ad0cf3
commit 17da91409a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 118 additions and 71 deletions
Download patch file Download diff file Expand all files Collapse all files

72
docs/CMakeLists.txt
View file

@ -8,43 +8,49 @@
# http://www.eclipse.org/org/documents/edl-v10.php.
#
# SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
include(FindPerl)
if(PERL_FOUND)
# These are all various expressions of the configuration schema
get_filename_component(config_c_PATH "../src/core/ddsi/src/q_config.c" REALPATH BASE_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
# although the following files are generated, we check them into source control for convenience
get_filename_component(config_rnc_PATH "../etc/cyclonedds.rnc" REALPATH BASE_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
get_filename_component(config_xsd_PATH "../etc/cyclonedds.xsd" REALPATH BASE_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
get_filename_component(config_md_PATH "./manual/options.md" REALPATH BASE_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
if(BUILD_SCHEMA OR BUILD_DOCS)
find_package(Perl REQUIRED)
add_custom_command(
OUTPUT
options.md cyclonedds.rnc
"${config_md_PATH}" "${config_rnc_PATH}"
COMMAND
${PERL_EXECUTABLE} -w "${CMAKE_CURRENT_SOURCE_DIR}/makernc.pl" "${CMAKE_CURRENT_SOURCE_DIR}/../src/core/ddsi/src/q_config.c" options.md cyclonedds.rnc
COMMAND
${PERL_EXECUTABLE} -w "${CMAKE_CURRENT_SOURCE_DIR}/compare.pl" options.md "${CMAKE_CURRENT_SOURCE_DIR}/manual/options.md"
COMMAND
${PERL_EXECUTABLE} -w "${CMAKE_CURRENT_SOURCE_DIR}/compare.pl" cyclonedds.rnc "${CMAKE_CURRENT_SOURCE_DIR}/../etc/cyclonedds.rnc"
${PERL_EXECUTABLE} -w "${CMAKE_CURRENT_SOURCE_DIR}/makernc.pl" "${config_c_PATH}" "${config_md_PATH}" "${config_rnc_PATH}"
COMMENT "Generating Relax NG schema and Markdown documentation for config options"
DEPENDS
"${CMAKE_CURRENT_SOURCE_DIR}/makernc.pl"
"${CMAKE_CURRENT_SOURCE_DIR}/../src/core/ddsi/src/q_config.c")
add_custom_target(options_doc ALL DEPENDS "options.md" "cyclonedds.rnc")
"${CMAKE_CURRENT_SOURCE_DIR}/makernc.pl"
"${config_c_PATH}")
add_custom_target(options_doc ALL DEPENDS "${config_md_PATH}" "${config_rnc_PATH}")
find_package(Java COMPONENTS Runtime)
if(JAVA_FOUND AND EXISTS "${TRANG_PATH}" OR EXISTS "$ENV{TRANG}")
if(NOT EXISTS "${TRANG_PATH}" AND EXISTS "$ENV{TRANG}")
message(STATUS "Setting TRANG_PATH to $ENV{TRANG}")
set(TRANG_PATH "$ENV{TRANG}" CACHE FILEPATH "Location of 'trang' for converting XML schemas" FORCE)
endif()
add_custom_command(
OUTPUT
cyclonedds.xsd
COMMAND
${Java_JAVA_EXECUTABLE} -jar "${TRANG_PATH}" -I rnc -O xsd cyclonedds.rnc cyclonedds.xsd
COMMAND
${PERL_EXECUTABLE} -w "${CMAKE_CURRENT_SOURCE_DIR}/compare.pl" cyclonedds.xsd "${CMAKE_CURRENT_SOURCE_DIR}/../etc/cyclonedds.xsd"
DEPENDS
"cyclonedds.rnc")
add_custom_target(options_xsd ALL DEPENDS "cyclonedds.xsd")
else()
message(STATUS "Java or not trang not found: not converting/checking RNC to XSD")
endif()
else()
message(STATUS "perl not found: not generating/checking options documentation and RNC")
find_package(Trang REQUIRED)
add_custom_command(
OUTPUT "${config_xsd_PATH}"
COMMAND ${Trang_TRANG_CMD} -I rnc -O xsd "${config_rnc_PATH}" "${config_xsd_PATH}"
COMMENT "Translating schema into XSD"
DEPENDS "${config_rnc_PATH}")
add_custom_target(options_xsd ALL DEPENDS "${config_xsd_PATH}")
endif()
add_subdirectory(manual)
if(BUILD_DOCS)
find_package(Sphinx REQUIRED breathe)
sphinx_add_docs(
docs
BREATHE_PROJECTS ddsc_api_docs
BUILDER html
SOURCE_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}")
add_dependencies(docs options_doc)
install(
DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
DESTINATION "${CMAKE_INSTALL_DOCDIR}/manual"
COMPONENT dev)
endif()