diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml index 9a56185c52c..db98018753d 100644 --- a/.github/workflows/doxygen.yml +++ b/.github/workflows/doxygen.yml @@ -1,4 +1,5 @@ name: Build and publish Doxygen documentation +# To test this workflow, push your changes to your fork's `develop` branch. on: push: branches: @@ -11,12 +12,18 @@ jobs: image: docker://rippleci/rippled-ci-builder:2944b78d22db steps: - name: checkout - uses: actions/checkout@v2 + uses: actions/checkout@v3 + - name: check environment + run: | + echo ${PATH} | tr ':' '\n' + cmake --version + doxygen --version + env - name: build run: | mkdir build cd build - cmake -DBoost_NO_BOOST_CMAKE=ON .. + cmake -Donly_docs=TRUE .. cmake --build . --target docs --parallel $(nproc) - name: publish uses: peaceiris/actions-gh-pages@v3 diff --git a/.github/workflows/nix.yml b/.github/workflows/nix.yml index a37ea9f132a..34030b3429b 100644 --- a/.github/workflows/nix.yml +++ b/.github/workflows/nix.yml @@ -74,7 +74,7 @@ jobs: run: | mkdir ${build_dir} cd ${build_dir} - conan install .. --build missing --settings build_type=${{ matrix.configuration }} --profile:build default --profile:host default + conan install .. --build missing --settings build_type=${{ matrix.configuration }} - name: configure run: | cd ${build_dir} diff --git a/Builds/CMake/RippledDocs.cmake b/Builds/CMake/RippledDocs.cmake index 883fd616256..e7c42942a77 100644 --- a/Builds/CMake/RippledDocs.cmake +++ b/Builds/CMake/RippledDocs.cmake @@ -2,85 +2,83 @@ docs target (optional) #]===================================================================] -# Early return if the `docs` directory is missing, -# e.g. when we are building a Conan package. -if(NOT EXISTS docs) +option(with_docs "Include the docs target?" FALSE) + +if(NOT (with_docs OR only_docs)) return() endif() -if (tests) - find_package (Doxygen) - if (NOT TARGET Doxygen::doxygen) - message (STATUS "doxygen executable not found -- skipping docs target") - return () - endif () - - set (doxygen_output_directory "${CMAKE_BINARY_DIR}/docs") - set (doxygen_include_path "${CMAKE_CURRENT_SOURCE_DIR}/src") - set (doxygen_index_file "${doxygen_output_directory}/html/index.html") - set (doxyfile "${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile") - - file (GLOB_RECURSE doxygen_input - docs/*.md - src/ripple/*.h - src/ripple/*.cpp - src/ripple/*.md - src/test/*.h - src/test/*.md - Builds/*/README.md) - list (APPEND doxygen_input - README.md - RELEASENOTES.md - src/README.md) - set (dependencies "${doxygen_input}" "${doxyfile}") - - function (verbose_find_path variable name) - # find_path sets a CACHE variable, so don't try using a "local" variable. - find_path (${variable} "${name}" ${ARGN}) - if (NOT ${variable}) - message (NOTICE "could not find ${name}") - else () - message (STATUS "found ${name}: ${${variable}}/${name}") - endif () - endfunction () - - verbose_find_path (doxygen_plantuml_jar_path plantuml.jar PATH_SUFFIXES share/plantuml) - verbose_find_path (doxygen_dot_path dot) - - # https://en.cppreference.com/w/Cppreference:Archives - # https://stackoverflow.com/questions/60822559/how-to-move-a-file-download-from-configure-step-to-build-step - set (download_script "${CMAKE_BINARY_DIR}/docs/download-cppreference.cmake") - file (WRITE - "${download_script}" - "file (DOWNLOAD \ - http://upload.cppreference.com/mwiki/images/b/b2/html_book_20190607.zip \ - ${CMAKE_BINARY_DIR}/docs/cppreference.zip \ - EXPECTED_HASH MD5=82b3a612d7d35a83e3cb1195a63689ab \ - )\n \ - execute_process ( \ - COMMAND \"${CMAKE_COMMAND}\" -E tar -xf cppreference.zip \ - )\n" - ) - set (tagfile "${CMAKE_BINARY_DIR}/docs/cppreference-doxygen-web.tag.xml") - add_custom_command ( - OUTPUT "${tagfile}" - COMMAND "${CMAKE_COMMAND}" -P "${download_script}" - WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/docs" - ) - set (doxygen_tagfiles "${tagfile}=http://en.cppreference.com/w/") - - add_custom_command ( - OUTPUT "${doxygen_index_file}" - COMMAND "${CMAKE_COMMAND}" -E env - "DOXYGEN_OUTPUT_DIRECTORY=${doxygen_output_directory}" - "DOXYGEN_INCLUDE_PATH=${doxygen_include_path}" - "DOXYGEN_TAGFILES=${doxygen_tagfiles}" - "DOXYGEN_PLANTUML_JAR_PATH=${doxygen_plantuml_jar_path}" - "DOXYGEN_DOT_PATH=${doxygen_dot_path}" - "${DOXYGEN_EXECUTABLE}" "${doxyfile}" - WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" - DEPENDS "${dependencies}" "${tagfile}") - add_custom_target (docs - DEPENDS "${doxygen_index_file}" - SOURCES "${dependencies}") -endif () +find_package(Doxygen) +if(NOT TARGET Doxygen::doxygen) + message(STATUS "doxygen executable not found -- skipping docs target") + return() +endif() + +set(doxygen_output_directory "${CMAKE_BINARY_DIR}/docs") +set(doxygen_include_path "${CMAKE_CURRENT_SOURCE_DIR}/src") +set(doxygen_index_file "${doxygen_output_directory}/html/index.html") +set(doxyfile "${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile") + +file(GLOB_RECURSE doxygen_input + docs/*.md + src/ripple/*.h + src/ripple/*.cpp + src/ripple/*.md + src/test/*.h + src/test/*.md + Builds/*/README.md) +list(APPEND doxygen_input + README.md + RELEASENOTES.md + src/README.md) +set(dependencies "${doxygen_input}" "${doxyfile}") + +function(verbose_find_path variable name) + # find_path sets a CACHE variable, so don't try using a "local" variable. + find_path(${variable} "${name}" ${ARGN}) + if(NOT ${variable}) + message(NOTICE "could not find ${name}") + else() + message(STATUS "found ${name}: ${${variable}}/${name}") + endif() +endfunction() + +verbose_find_path(doxygen_plantuml_jar_path plantuml.jar PATH_SUFFIXES share/plantuml) +verbose_find_path(doxygen_dot_path dot) + +# https://en.cppreference.com/w/Cppreference:Archives +# https://stackoverflow.com/questions/60822559/how-to-move-a-file-download-from-configure-step-to-build-step +set(download_script "${CMAKE_BINARY_DIR}/docs/download-cppreference.cmake") +file(WRITE + "${download_script}" + "file(DOWNLOAD \ + http://upload.cppreference.com/mwiki/images/b/b2/html_book_20190607.zip \ + ${CMAKE_BINARY_DIR}/docs/cppreference.zip \ + EXPECTED_HASH MD5=82b3a612d7d35a83e3cb1195a63689ab \ + )\n \ + execute_process( \ + COMMAND \"${CMAKE_COMMAND}\" -E tar -xf cppreference.zip \ + )\n" +) +set(tagfile "${CMAKE_BINARY_DIR}/docs/cppreference-doxygen-web.tag.xml") +add_custom_command( + OUTPUT "${tagfile}" + COMMAND "${CMAKE_COMMAND}" -P "${download_script}" + WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/docs" +) +set(doxygen_tagfiles "${tagfile}=http://en.cppreference.com/w/") + +add_custom_command( + OUTPUT "${doxygen_index_file}" + COMMAND "${CMAKE_COMMAND}" -E env + "DOXYGEN_OUTPUT_DIRECTORY=${doxygen_output_directory}" + "DOXYGEN_INCLUDE_PATH=${doxygen_include_path}" + "DOXYGEN_TAGFILES=${doxygen_tagfiles}" + "DOXYGEN_PLANTUML_JAR_PATH=${doxygen_plantuml_jar_path}" + "DOXYGEN_DOT_PATH=${doxygen_dot_path}" + "${DOXYGEN_EXECUTABLE}" "${doxyfile}" + WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" + DEPENDS "${dependencies}" "${tagfile}") +add_custom_target(docs + DEPENDS "${doxygen_index_file}" + SOURCES "${dependencies}") diff --git a/CMakeLists.txt b/CMakeLists.txt index a3696e89d04..da2ea1a5307 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -58,6 +58,12 @@ endif () include(RippledCompiler) include(RippledInterface) +option(only_docs "Include only the docs target?" FALSE) +include(RippledDocs) +if(only_docs) + return() +endif() + ### include(deps/Boost) @@ -119,5 +125,4 @@ include(RippledCore) include(RippledInstall) include(RippledCov) include(RippledMultiConfig) -include(RippledDocs) include(RippledValidatorKeys)