From 36addaa96c88b9eb7a63ea4e2009025a3a6f4298 Mon Sep 17 00:00:00 2001 From: John Freeman Date: Mon, 16 Mar 2020 11:04:06 -0500 Subject: [PATCH 01/13] Fix Doxygen build --- Builds/CMake/RippledDocs.cmake | 63 ++++++++++++++++++------------ docs/Dockerfile | 3 +- docs/{source.dox => Doxyfile} | 70 ++++------------------------------ docs/README.md | 4 +- 4 files changed, 51 insertions(+), 89 deletions(-) rename docs/{source.dox => Doxyfile} (82%) diff --git a/Builds/CMake/RippledDocs.cmake b/Builds/CMake/RippledDocs.cmake index be964a56049..0e24a6013ba 100644 --- a/Builds/CMake/RippledDocs.cmake +++ b/Builds/CMake/RippledDocs.cmake @@ -3,29 +3,44 @@ #]===================================================================] find_package (Doxygen) -if (TARGET Doxygen::doxygen) - set (doc_srcs docs/source.dox) - file (GLOB_RECURSE other_docs docs/*.md) - list (APPEND doc_srcs "${other_docs}") - # read the source config and make a modified one - # that points the output files to our build directory - file (READ "${CMAKE_CURRENT_SOURCE_DIR}/docs/source.dox" dox_content) - string (REGEX REPLACE "[\t ]*OUTPUT_DIRECTORY[\t ]*=(.*)" - "OUTPUT_DIRECTORY=${CMAKE_BINARY_DIR}\n\\1" - new_config "${dox_content}") - file (WRITE "${CMAKE_BINARY_DIR}/source.dox" "${new_config}") - add_custom_target (docs - COMMAND "${DOXYGEN_EXECUTABLE}" "${CMAKE_BINARY_DIR}/source.dox" - BYPRODUCTS "${CMAKE_BINARY_DIR}/html_doc/index.html" - WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/docs" - SOURCES "${doc_srcs}") - if (is_multiconfig) - set_property ( - SOURCE ${doc_srcs} - APPEND - PROPERTY HEADER_FILE_ONLY - true) - endif () -else () +if (NOT TARGET Doxygen::doxygen) message (STATUS "doxygen executable not found -- skipping docs target") + return () +endif () + +set (doxygen_output_directory "${CMAKE_BINARY_DIR}/html_doc") +set (doxygen_index_file "${doxygen_output_directory}/index.html") +set (doxyfile_in "${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile") +set (doxyfile_out "${CMAKE_BINARY_DIR}/Doxyfile") + +file (GLOB_RECURSE doxygen_input + docs/*.md + src/ripple/*.h + 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}" docs/Doxyfile) + +# Substitute doxygen_output_directory. +# TODO: Generate this file at build time, not configure time. +configure_file ("${doxyfile_in}" "${doxyfile_out}" @ONLY) + +add_custom_command ( + OUTPUT "${doxygen_index_file}" + COMMAND "${DOXYGEN_EXECUTABLE}" "${doxyfile_out}" + WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/docs" + DEPENDS "${dependencies}") +add_custom_target (docs + DEPENDS "${doxygen_index_file}" + SOURCES "${dependencies}") +if (is_multiconfig) + set_property ( + SOURCE ${dependencies} + APPEND PROPERTY + HEADER_FILE_ONLY true) endif () diff --git a/docs/Dockerfile b/docs/Dockerfile index dd33d95e647..a0eec1681a9 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -28,4 +28,5 @@ RUN mkdir -p /opt/plantuml RUN wget -O /opt/plantuml/plantuml.jar http://sourceforge.net/projects/plantuml/files/plantuml.jar/download ENV PLANTUML_JAR=/opt/plantuml/plantuml.jar -CMD cd /opt/rippled/docs && doxygen source.dox +RUN sed -i -e 's/@doxygen_output_directory@//' /opt/rippled/docs/Doxyfile +CMD cd /opt/rippled/docs && doxygen Doxyfile diff --git a/docs/source.dox b/docs/Doxyfile similarity index 82% rename from docs/source.dox rename to docs/Doxyfile index fb2fa12ff6e..a143b9dfbf1 100644 --- a/docs/source.dox +++ b/docs/Doxyfile @@ -7,7 +7,7 @@ PROJECT_NUMBER = PROJECT_BRIEF = C++ Library PROJECT_LOGO = PROJECT_LOGO = images/LogoForDocumentation.png -OUTPUT_DIRECTORY = +OUTPUT_DIRECTORY = @doxygen_output_directory@ CREATE_SUBDIRS = NO ALLOW_UNICODE_NAMES = NO OUTPUT_LANGUAGE = English @@ -104,71 +104,17 @@ WARN_LOGFILE = # Configuration options related to the input files #--------------------------------------------------------------------------- INPUT = \ -\ - ../src/ripple/app/misc/TxQ.h \ - ../src/ripple/app/tx/apply.h \ - ../src/ripple/app/tx/applySteps.h \ - ../src/ripple/protocol/STObject.h \ - ../src/ripple/protocol/JsonFields.h \ - ../src/test/jtx/AbstractClient.h \ - ../src/test/jtx/JSONRPCClient.h \ - ../src/test/jtx/WSClient.h \ - ../src/ripple/consensus/Consensus.h \ - ../src/ripple/consensus/ConsensusProposal.h \ - ../src/ripple/consensus/ConsensusTypes.h \ - ../src/ripple/consensus/DisputedTx.h \ - ../src/ripple/consensus/LedgerTiming.h \ - ../src/ripple/consensus/LedgerTrie.h \ - ../src/ripple/consensus/Validations.h \ - ../src/ripple/consensus/ConsensusParms.h \ - ../src/ripple/app/consensus/RCLCxTx.h \ - ../src/ripple/app/consensus/RCLCxLedger.h \ - ../src/ripple/app/consensus/RCLConsensus.h \ - ../src/ripple/app/consensus/RCLCxPeerPos.h \ - ../src/ripple/app/tx/apply.h \ - ../src/ripple/app/tx/applySteps.h \ - ../src/ripple/app/tx/impl/InvariantCheck.h \ - ../src/ripple/app/consensus/RCLValidations.h \ + ../docs \ + ../src/ripple \ + ../src/test \ ../src/README.md \ - ../src/ripple/README.md \ ../README.md \ ../RELEASENOTES.md \ - ../docs/CodingStyle.md \ - ../docs/CheatSheet.md \ - ../docs/README.md \ - ../docs/sample_chart.doc \ - ../docs/HeapProfiling.md \ - ../docs/Docker.md \ - ../docs/consensus.md \ - ../Builds/macos/README.md \ - ../Builds/linux/README.md \ - ../Builds/VisualStudio2017/README.md \ - ../src/ripple/consensus/README.md \ - ../src/ripple/app/consensus/README.md \ - ../src/test/csf/README.md \ - ../src/ripple/basics/README.md \ - ../src/ripple/crypto/README.md \ - ../src/ripple/peerfinder/README.md \ - ../src/ripple/app/misc/README.md \ - ../src/ripple/app/misc/FeeEscalation.md \ - ../src/ripple/app/ledger/README.md \ - ../src/ripple/app/paths/README.md \ - ../src/ripple/app/tx/README.md \ - ../src/ripple/proto/README.md \ - ../src/ripple/shamap/README.md \ - ../src/ripple/protocol/README.md \ - ../src/ripple/json/README.md \ - ../src/ripple/json/TODO.md \ - ../src/ripple/resource/README.md \ - ../src/ripple/rpc/README.md \ - ../src/ripple/overlay/README.md \ - ../src/ripple/nodestore/README.md \ - ../src/ripple/nodestore/Benchmarks.md \ INPUT_ENCODING = UTF-8 -FILE_PATTERNS = -RECURSIVE = NO +FILE_PATTERNS = *.h *.cpp *.md +RECURSIVE = YES EXCLUDE = EXCLUDE_SYMLINKS = NO EXCLUDE_PATTERNS = @@ -190,7 +136,7 @@ USE_MDFILE_AS_MAINPAGE = ../src/README.md #--------------------------------------------------------------------------- # Configuration options related to source browsing #--------------------------------------------------------------------------- -SOURCE_BROWSER = NO +SOURCE_BROWSER = YES INLINE_SOURCES = NO STRIP_CODE_COMMENTS = YES REFERENCED_BY_RELATION = NO @@ -213,7 +159,7 @@ IGNORE_PREFIX = # Configuration options related to the HTML output #--------------------------------------------------------------------------- GENERATE_HTML = YES -HTML_OUTPUT = html_doc +HTML_OUTPUT = . HTML_FILE_EXTENSION = .html HTML_HEADER = HTML_FOOTER = diff --git a/docs/README.md b/docs/README.md index 04e25775273..f46f7f53538 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,7 +3,7 @@ ## Specifying Files To specify the source files for which to build documentation, modify `INPUT` -and its related fields in `docs/source.dox`. Note that the `INPUT` paths are +and its related fields in `docs/Doxyfile`. Note that the `INPUT` paths are relative to the `docs/` directory. ## Install Dependencies @@ -48,7 +48,7 @@ From the rippled root folder: ``` cd docs mkdir -p html_doc -doxygen source.dox +doxygen Doxyfile ``` The output will be in `docs/html_doc`. From 07f8d87a0695504af268d85eabef98b3cec6f6b2 Mon Sep 17 00:00:00 2001 From: John Freeman Date: Tue, 17 Mar 2020 11:50:59 -0500 Subject: [PATCH 02/13] Relativize Doxyfile to root directory --- Builds/CMake/RippledDocs.cmake | 2 +- docs/Doxyfile | 24 ++++++++++++------------ 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/Builds/CMake/RippledDocs.cmake b/Builds/CMake/RippledDocs.cmake index 0e24a6013ba..97d954d2b8e 100644 --- a/Builds/CMake/RippledDocs.cmake +++ b/Builds/CMake/RippledDocs.cmake @@ -33,7 +33,7 @@ configure_file ("${doxyfile_in}" "${doxyfile_out}" @ONLY) add_custom_command ( OUTPUT "${doxygen_index_file}" COMMAND "${DOXYGEN_EXECUTABLE}" "${doxyfile_out}" - WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/docs" + WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" DEPENDS "${dependencies}") add_custom_target (docs DEPENDS "${doxygen_index_file}" diff --git a/docs/Doxyfile b/docs/Doxyfile index a143b9dfbf1..5396de5cef5 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -17,7 +17,7 @@ ABBREVIATE_BRIEF = ALWAYS_DETAILED_SEC = NO INLINE_INHERITED_MEMB = YES FULL_PATH_NAMES = NO -STRIP_FROM_PATH = ../src/ +STRIP_FROM_PATH = src/ STRIP_FROM_INC_PATH = SHORT_NAMES = NO JAVADOC_AUTOBRIEF = YES @@ -104,12 +104,12 @@ WARN_LOGFILE = # Configuration options related to the input files #--------------------------------------------------------------------------- INPUT = \ - ../docs \ - ../src/ripple \ - ../src/test \ - ../src/README.md \ - ../README.md \ - ../RELEASENOTES.md \ + docs \ + src/ripple \ + src/test \ + src/README.md \ + README.md \ + RELEASENOTES.md \ INPUT_ENCODING = UTF-8 @@ -123,15 +123,15 @@ EXAMPLE_PATH = EXAMPLE_PATTERNS = EXAMPLE_RECURSIVE = NO IMAGE_PATH = \ - ./images/ \ - ./images/consensus/ \ - ../src/test/csf/ \ + docs/images/ \ + docs/images/consensus/ \ + src/test/csf/ \ INPUT_FILTER = FILTER_PATTERNS = FILTER_SOURCE_FILES = NO FILTER_SOURCE_PATTERNS = -USE_MDFILE_AS_MAINPAGE = ../src/README.md +USE_MDFILE_AS_MAINPAGE = src/README.md #--------------------------------------------------------------------------- # Configuration options related to source browsing @@ -286,7 +286,7 @@ ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES SEARCH_INCLUDES = YES -INCLUDE_PATH = ../ +INCLUDE_PATH = ./ INCLUDE_FILE_PATTERNS = PREDEFINED = DOXYGEN \ GENERATING_DOCS \ From 722ceb44f14317ff5eef434aec60255bcd69a915 Mon Sep 17 00:00:00 2001 From: John Freeman Date: Tue, 17 Mar 2020 12:14:14 -0500 Subject: [PATCH 03/13] Add workflow to build and publish documentation --- .github/workflows/main.yml | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 .github/workflows/main.yml diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml new file mode 100644 index 00000000000..83fc1a87583 --- /dev/null +++ b/.github/workflows/main.yml @@ -0,0 +1,23 @@ +name: Build and publish documentation +on: + push: + branches: + - develop + +jobs: + job: + runs-on: ubuntu-18.04 + steps: + - name: checkout + uses: actions/checkout@v2 + - name: set OUTPUT_DIRECTORY + run: echo 'OUTPUT_DIRECTORY = html' >> docs/Doxyfile + - name: build + uses: mattnotmitt/doxygen-action@v1 + with: + doxyfile-path: 'docs/Doxyfile' + - name: publish + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./html From 48d8d41e8eeb383daade18d87f63008b769ac54f Mon Sep 17 00:00:00 2001 From: John Freeman Date: Mon, 23 Mar 2020 18:53:48 -0500 Subject: [PATCH 04/13] Cross-reference standard library to cppreference.com --- Builds/CMake/RippledDocs.cmake | 28 +++++++++++++++++++++++++--- docs/Dockerfile | 3 ++- docs/Doxyfile | 4 ++-- 3 files changed, 29 insertions(+), 6 deletions(-) diff --git a/Builds/CMake/RippledDocs.cmake b/Builds/CMake/RippledDocs.cmake index 97d954d2b8e..68dfef8bb8c 100644 --- a/Builds/CMake/RippledDocs.cmake +++ b/Builds/CMake/RippledDocs.cmake @@ -8,10 +8,10 @@ if (NOT TARGET Doxygen::doxygen) return () endif () -set (doxygen_output_directory "${CMAKE_BINARY_DIR}/html_doc") +set (doxygen_output_directory "${CMAKE_BINARY_DIR}/docs/html") set (doxygen_index_file "${doxygen_output_directory}/index.html") set (doxyfile_in "${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile") -set (doxyfile_out "${CMAKE_BINARY_DIR}/Doxyfile") +set (doxyfile_out "${CMAKE_BINARY_DIR}/docs/Doxyfile") file (GLOB_RECURSE doxygen_input docs/*.md @@ -26,6 +26,28 @@ list (APPEND doxygen_input src/README.md) set (dependencies "${doxygen_input}" docs/Doxyfile) +# 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_tag_files "${tagfile}=http://en.cppreference.com/w/") + # Substitute doxygen_output_directory. # TODO: Generate this file at build time, not configure time. configure_file ("${doxyfile_in}" "${doxyfile_out}" @ONLY) @@ -34,7 +56,7 @@ add_custom_command ( OUTPUT "${doxygen_index_file}" COMMAND "${DOXYGEN_EXECUTABLE}" "${doxyfile_out}" WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" - DEPENDS "${dependencies}") + DEPENDS "${dependencies}" "${tagfile}") add_custom_target (docs DEPENDS "${doxygen_index_file}" SOURCES "${dependencies}") diff --git a/docs/Dockerfile b/docs/Dockerfile index a0eec1681a9..3e5944b653f 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -28,5 +28,6 @@ RUN mkdir -p /opt/plantuml RUN wget -O /opt/plantuml/plantuml.jar http://sourceforge.net/projects/plantuml/files/plantuml.jar/download ENV PLANTUML_JAR=/opt/plantuml/plantuml.jar -RUN sed -i -e 's/@doxygen_output_directory@//' /opt/rippled/docs/Doxyfile +RUN sed -i -e 's/@doxygen_output_directory@//' -e 's/@doxygen_tag_files@//' \ + /opt/rippled/docs/Doxyfile CMD cd /opt/rippled/docs && doxygen Doxyfile diff --git a/docs/Doxyfile b/docs/Doxyfile index 5396de5cef5..4f812e382d6 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -83,7 +83,7 @@ ENABLED_SECTIONS = MAX_INITIALIZER_LINES = 30 SHOW_USED_FILES = NO SHOW_FILES = NO -SHOW_NAMESPACES = NO +SHOW_NAMESPACES = YES FILE_VERSION_FILTER = LAYOUT_FILE = CITE_BIB_FILES = @@ -299,7 +299,7 @@ SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- # Configuration options related to external references #--------------------------------------------------------------------------- -TAGFILES = +TAGFILES = @doxygen_tag_files@ GENERATE_TAGFILE = ALLEXTERNALS = NO EXTERNAL_GROUPS = YES From 01379dca517ab29aacca51e21f68f63109c45bf7 Mon Sep 17 00:00:00 2001 From: John Freeman Date: Mon, 23 Mar 2020 20:29:39 -0500 Subject: [PATCH 05/13] Find PlantUML for Doxygen --- Builds/CMake/RippledDocs.cmake | 5 +++++ docs/Doxyfile | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/Builds/CMake/RippledDocs.cmake b/Builds/CMake/RippledDocs.cmake index 68dfef8bb8c..524d87a8ca7 100644 --- a/Builds/CMake/RippledDocs.cmake +++ b/Builds/CMake/RippledDocs.cmake @@ -26,6 +26,11 @@ list (APPEND doxygen_input src/README.md) set (dependencies "${doxygen_input}" docs/Doxyfile) +find_path (doxygen_plantuml_jar_path plantuml.jar PATH_SUFFIXES share/plantuml) +if (NOT doxygen_plantuml_jar_path) + set (doxygen_plantuml_jar_path) +endif () + # 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") diff --git a/docs/Doxyfile b/docs/Doxyfile index 4f812e382d6..499ebafe08e 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -336,7 +336,7 @@ DOT_PATH = DOTFILE_DIRS = MSCFILE_DIRS = DIAFILE_DIRS = -PLANTUML_JAR_PATH = $(PLANTUML_JAR) +PLANTUML_JAR_PATH = @doxygen_plantuml_jar_path@ PLANTUML_INCLUDE_PATH = DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 0 From 1f1838935b2a148f7569248242ddc493ec36ed41 Mon Sep 17 00:00:00 2001 From: John Freeman Date: Tue, 24 Mar 2020 14:23:38 -0500 Subject: [PATCH 06/13] Use environment variables in Doxyfile --- Builds/CMake/RippledDocs.cmake | 17 ++++++++--------- bin/ci/ubuntu/build-and-test.sh | 2 +- docs/Dockerfile | 7 +++---- docs/Doxyfile | 6 +++--- docs/README.md | 31 +++++++++++++++---------------- 5 files changed, 30 insertions(+), 33 deletions(-) diff --git a/Builds/CMake/RippledDocs.cmake b/Builds/CMake/RippledDocs.cmake index 524d87a8ca7..8263a4a80c2 100644 --- a/Builds/CMake/RippledDocs.cmake +++ b/Builds/CMake/RippledDocs.cmake @@ -10,8 +10,7 @@ endif () set (doxygen_output_directory "${CMAKE_BINARY_DIR}/docs/html") set (doxygen_index_file "${doxygen_output_directory}/index.html") -set (doxyfile_in "${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile") -set (doxyfile_out "${CMAKE_BINARY_DIR}/docs/Doxyfile") +set (doxyfile "${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile") file (GLOB_RECURSE doxygen_input docs/*.md @@ -24,7 +23,7 @@ list (APPEND doxygen_input README.md RELEASENOTES.md src/README.md) -set (dependencies "${doxygen_input}" docs/Doxyfile) +set (dependencies "${doxygen_input}" "${doxyfile}") find_path (doxygen_plantuml_jar_path plantuml.jar PATH_SUFFIXES share/plantuml) if (NOT doxygen_plantuml_jar_path) @@ -51,15 +50,15 @@ add_custom_command ( COMMAND "${CMAKE_COMMAND}" -P "${download_script}" WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/docs" ) -set (doxygen_tag_files "${tagfile}=http://en.cppreference.com/w/") - -# Substitute doxygen_output_directory. -# TODO: Generate this file at build time, not configure time. -configure_file ("${doxyfile_in}" "${doxyfile_out}" @ONLY) +set (doxygen_tagfiles "${tagfile}=http://en.cppreference.com/w/") add_custom_command ( OUTPUT "${doxygen_index_file}" - COMMAND "${DOXYGEN_EXECUTABLE}" "${doxyfile_out}" + COMMAND "${CMAKE_COMMAND}" -E env + "DOXYGEN_OUTPUT_DIRECTORY=${doxygen_output_directory}" + "DOXYGEN_TAGFILES=${doxygen_tagfiles}" + "DOXYGEN_PLANTUML_JAR_PATH=${doxygen_plantuml_jar_path}" + "${DOXYGEN_EXECUTABLE}" "${doxyfile}" WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" DEPENDS "${dependencies}" "${tagfile}") add_custom_target (docs diff --git a/bin/ci/ubuntu/build-and-test.sh b/bin/ci/ubuntu/build-and-test.sh index 41f433ef1ae..7ffad801dd1 100755 --- a/bin/ci/ubuntu/build-and-test.sh +++ b/bin/ci/ubuntu/build-and-test.sh @@ -105,7 +105,7 @@ ${time} eval cmake --build . ${BUILDARGS} -- ${BUILDTOOLARGS} if [[ ${TARGET} == "docs" ]]; then ## mimic the standard test output for docs build ## to make controlling processes like jenkins happy - if [ -f html_doc/index.html ]; then + if [ -f docs/html/index.html ]; then echo "1 case, 1 test total, 0 failures" else echo "1 case, 1 test total, 1 failures" diff --git a/docs/Dockerfile b/docs/Dockerfile index 3e5944b653f..d716ca21315 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -26,8 +26,7 @@ RUN rm -rf /tmp/doxygen-1.8.14 RUN mkdir -p /opt/plantuml RUN wget -O /opt/plantuml/plantuml.jar http://sourceforge.net/projects/plantuml/files/plantuml.jar/download -ENV PLANTUML_JAR=/opt/plantuml/plantuml.jar +ENV DOXYGEN_PLANTUML_JAR_PATH=/opt/plantuml/plantuml.jar -RUN sed -i -e 's/@doxygen_output_directory@//' -e 's/@doxygen_tag_files@//' \ - /opt/rippled/docs/Doxyfile -CMD cd /opt/rippled/docs && doxygen Doxyfile +ENV DOXYGEN_OUTPUT_DIRECTORY=html +CMD cd /opt/rippled && doxygen docs/Doxyfile diff --git a/docs/Doxyfile b/docs/Doxyfile index 499ebafe08e..0d70dc210a3 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -7,7 +7,7 @@ PROJECT_NUMBER = PROJECT_BRIEF = C++ Library PROJECT_LOGO = PROJECT_LOGO = images/LogoForDocumentation.png -OUTPUT_DIRECTORY = @doxygen_output_directory@ +OUTPUT_DIRECTORY = $(DOXYGEN_OUTPUT_DIRECTORY) CREATE_SUBDIRS = NO ALLOW_UNICODE_NAMES = NO OUTPUT_LANGUAGE = English @@ -299,7 +299,7 @@ SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- # Configuration options related to external references #--------------------------------------------------------------------------- -TAGFILES = @doxygen_tag_files@ +TAGFILES = $(DOXYGEN_TAGFILES) GENERATE_TAGFILE = ALLEXTERNALS = NO EXTERNAL_GROUPS = YES @@ -336,7 +336,7 @@ DOT_PATH = DOTFILE_DIRS = MSCFILE_DIRS = DIAFILE_DIRS = -PLANTUML_JAR_PATH = @doxygen_plantuml_jar_path@ +PLANTUML_JAR_PATH = $(DOXYGEN_PLANTUML_JAR_PATH) PLANTUML_INCLUDE_PATH = DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 0 diff --git a/docs/README.md b/docs/README.md index f46f7f53538..ba78df2ec3b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,11 +1,5 @@ # Building documentation -## Specifying Files - -To specify the source files for which to build documentation, modify `INPUT` -and its related fields in `docs/Doxyfile`. Note that the `INPUT` paths are -relative to the `docs/` directory. - ## Install Dependencies ### Windows @@ -30,7 +24,7 @@ Install these dependencies: ### [Optional] Install Plantuml (all platforms) -Doxygen supports the optional use of [plantuml](http://plantuml.com) to +Doxygen supports the optional use of [plantuml](http://plantuml.com) to generate diagrams from `@startuml` sections. We don't currently rely on this functionality for docs, so it's largely optional. Requirements: @@ -40,22 +34,28 @@ functionality for docs, so it's largely optional. Requirements: Set a system environment variable named `PLANTUML_JAR` with a value of the fullpath to the file system location of the `plantuml.jar` file you downloaded. -## Do it -### all platforms +## Configuration + +You should set these environment variables: + +- `DOXYGEN_OUTPUT_DIRECTORY` +- `DOXYGEN_PLANTUML_JAR_PATH` + +## Build From the rippled root folder: + ``` -cd docs -mkdir -p html_doc -doxygen Doxyfile +doxygen docs/Doxyfile ``` -The output will be in `docs/html_doc`. + +The output will be wherever you chose for `DOXYGEN_OUTPUT_DIRECTORY`. ## Docker (applicable to all platforms) - + Instead of installing the doxygen tools locally, you can use the provided `Dockerfile` to create an ubuntu based image for running the tools: @@ -72,5 +72,4 @@ Then to run the image, from the rippled root folder: sudo docker run -v $PWD:/opt/rippled --rm rippled-docs ``` -The output will be in `docs/html_doc`. - +The output will be in `html`. From 9a93dc21a187712fc7624c1f71363e1365d61f36 Mon Sep 17 00:00:00 2001 From: John Freeman Date: Wed, 25 Mar 2020 15:24:29 -0500 Subject: [PATCH 07/13] Update instructions --- docs/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/README.md b/docs/README.md index ba78df2ec3b..3345ee828f3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -31,11 +31,11 @@ functionality for docs, so it's largely optional. Requirements: 1. Download/install a functioning java runtime, if you don't already have one. 2. Download [plantuml](http://plantuml.com) from [here](http://sourceforge.net/projects/plantuml/files/plantuml.jar/download). - Set a system environment variable named `PLANTUML_JAR` with a value of the fullpath - to the file system location of the `plantuml.jar` file you downloaded. + Set a system environment variable named `DOXYGEN_PLANTUML_JAR_PATH` to + the absolute path of the `plantuml.jar` file you downloaded. -## Configuration +## Configure You should set these environment variables: From 7d6e3bb886b44bb1bc1dc0e6f073134638f087e8 Mon Sep 17 00:00:00 2001 From: John Freeman Date: Tue, 31 Mar 2020 15:01:05 -0500 Subject: [PATCH 08/13] Configure Doxygen to use dot --- Builds/CMake/RippledDocs.cmake | 18 ++++++++++++++---- docs/Doxyfile | 7 ++++--- 2 files changed, 18 insertions(+), 7 deletions(-) diff --git a/Builds/CMake/RippledDocs.cmake b/Builds/CMake/RippledDocs.cmake index 8263a4a80c2..e7d528a6139 100644 --- a/Builds/CMake/RippledDocs.cmake +++ b/Builds/CMake/RippledDocs.cmake @@ -15,6 +15,7 @@ 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 @@ -25,10 +26,18 @@ list (APPEND doxygen_input src/README.md) set (dependencies "${doxygen_input}" "${doxyfile}") -find_path (doxygen_plantuml_jar_path plantuml.jar PATH_SUFFIXES share/plantuml) -if (NOT doxygen_plantuml_jar_path) - set (doxygen_plantuml_jar_path) -endif () +function (verbose_find_path variable name) + find_path(path "${name}" ${ARGN}) + if (NOT path) + message (WARNING "could not find ${name}") + else () + message (STATUS "found ${name}: ${path}/${name}") + set (variable "${path}" PARENT_SCOPE) + 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 @@ -58,6 +67,7 @@ add_custom_command ( "DOXYGEN_OUTPUT_DIRECTORY=${doxygen_output_directory}" "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}") diff --git a/docs/Doxyfile b/docs/Doxyfile index 0d70dc210a3..ee28af4f1d2 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -35,7 +35,7 @@ OPTIMIZE_OUTPUT_VHDL = NO EXTENSION_MAPPING = MARKDOWN_SUPPORT = YES AUTOLINK_SUPPORT = YES -BUILTIN_STL_SUPPORT = NO +BUILTIN_STL_SUPPORT = YES CPP_CLI_SUPPORT = NO SIP_SUPPORT = NO IDL_PROPERTY_SUPPORT = YES @@ -313,7 +313,8 @@ CLASS_DIAGRAMS = NO MSCGEN_PATH = DIA_PATH = HIDE_UNDOC_RELATIONS = YES -HAVE_DOT = NO +HAVE_DOT = YES +# DOT_NUM_THREADS = 0 means 1 for every processor. DOT_NUM_THREADS = 0 DOT_FONTNAME = Helvetica DOT_FONTSIZE = 10 @@ -332,7 +333,7 @@ GRAPHICAL_HIERARCHY = YES DIRECTORY_GRAPH = YES DOT_IMAGE_FORMAT = png INTERACTIVE_SVG = NO -DOT_PATH = +DOT_PATH = $(DOXYGEN_DOT_PATH) DOTFILE_DIRS = MSCFILE_DIRS = DIAFILE_DIRS = From fd9a5ca0bb20be5cfd7d5ea907a5bbec20b78758 Mon Sep 17 00:00:00 2001 From: John Freeman Date: Tue, 31 Mar 2020 17:11:25 -0500 Subject: [PATCH 09/13] Generate call graph for InboundLedgersImp::acquire --- src/ripple/app/ledger/impl/InboundLedgers.cpp | 1 + 1 file changed, 1 insertion(+) diff --git a/src/ripple/app/ledger/impl/InboundLedgers.cpp b/src/ripple/app/ledger/impl/InboundLedgers.cpp index 589dfc3d79f..cd78f8ee80c 100644 --- a/src/ripple/app/ledger/impl/InboundLedgers.cpp +++ b/src/ripple/app/ledger/impl/InboundLedgers.cpp @@ -64,6 +64,7 @@ class InboundLedgersImp { } + /** @callgraph */ std::shared_ptr acquire(uint256 const& hash, std::uint32_t seq, InboundLedger::Reason reason) override From 2aa217c47a372f4df94cb501a8c28800dbc8a248 Mon Sep 17 00:00:00 2001 From: John Freeman Date: Tue, 31 Mar 2020 18:25:55 -0500 Subject: [PATCH 10/13] Fix inadvertent use of CACHE variable --- Builds/CMake/RippledDocs.cmake | 16 ++++++++++------ docs/Doxyfile | 4 ++-- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/Builds/CMake/RippledDocs.cmake b/Builds/CMake/RippledDocs.cmake index e7d528a6139..290872be5d4 100644 --- a/Builds/CMake/RippledDocs.cmake +++ b/Builds/CMake/RippledDocs.cmake @@ -8,8 +8,9 @@ if (NOT TARGET Doxygen::doxygen) return () endif () -set (doxygen_output_directory "${CMAKE_BINARY_DIR}/docs/html") -set (doxygen_index_file "${doxygen_output_directory}/index.html") +set (doxygen_output_directory "${CMAKE_BINARY_DIR}/docs") +set (doxygen_include_path "${CMAKE_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 @@ -27,12 +28,14 @@ list (APPEND doxygen_input set (dependencies "${doxygen_input}" "${doxyfile}") function (verbose_find_path variable name) - find_path(path "${name}" ${ARGN}) - if (NOT path) + # Someone set the variable "path" as a CACHE variable, + # which means we cannot use it as a local variable. + find_path (vfp_path "${name}" ${ARGN}) + if (NOT vfp_path) message (WARNING "could not find ${name}") else () - message (STATUS "found ${name}: ${path}/${name}") - set (variable "${path}" PARENT_SCOPE) + message (STATUS "found ${name}: ${vfp_path}/${name}") + set (${variable} "${vfp_path}" PARENT_SCOPE) endif () endfunction () @@ -65,6 +68,7 @@ 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}" diff --git a/docs/Doxyfile b/docs/Doxyfile index ee28af4f1d2..2b17626db68 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -159,7 +159,7 @@ IGNORE_PREFIX = # Configuration options related to the HTML output #--------------------------------------------------------------------------- GENERATE_HTML = YES -HTML_OUTPUT = . +HTML_OUTPUT = html HTML_FILE_EXTENSION = .html HTML_HEADER = HTML_FOOTER = @@ -286,7 +286,7 @@ ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES SEARCH_INCLUDES = YES -INCLUDE_PATH = ./ +INCLUDE_PATH = $(DOXYGEN_INCLUDE_PATH) INCLUDE_FILE_PATTERNS = PREDEFINED = DOXYGEN \ GENERATING_DOCS \ From 9f425912612e398e61cd5cf3381eac8cb47290d9 Mon Sep 17 00:00:00 2001 From: John Freeman Date: Wed, 1 Apr 2020 08:24:17 -0500 Subject: [PATCH 11/13] Fix the last fix --- Builds/CMake/RippledDocs.cmake | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/Builds/CMake/RippledDocs.cmake b/Builds/CMake/RippledDocs.cmake index 290872be5d4..b168b8d0154 100644 --- a/Builds/CMake/RippledDocs.cmake +++ b/Builds/CMake/RippledDocs.cmake @@ -28,14 +28,12 @@ list (APPEND doxygen_input set (dependencies "${doxygen_input}" "${doxyfile}") function (verbose_find_path variable name) - # Someone set the variable "path" as a CACHE variable, - # which means we cannot use it as a local variable. - find_path (vfp_path "${name}" ${ARGN}) - if (NOT vfp_path) + # find_path sets a CACHE variable, so don't try using a "local" variable. + find_path (${variable} "${name}" ${ARGN}) + if (NOT ${variable}) message (WARNING "could not find ${name}") else () - message (STATUS "found ${name}: ${vfp_path}/${name}") - set (${variable} "${vfp_path}" PARENT_SCOPE) + message (STATUS "found ${name}: ${${variable}}/${name}") endif () endfunction () From 85509179f8743f45513e0e198dde4df4f09057c2 Mon Sep 17 00:00:00 2001 From: John Freeman Date: Wed, 1 Apr 2020 11:28:09 -0500 Subject: [PATCH 12/13] Tidy up Doxyfile --- docs/Doxyfile | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index 2b17626db68..48a0b5d1e1a 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -4,9 +4,9 @@ DOXYFILE_ENCODING = UTF-8 PROJECT_NAME = "rippled" PROJECT_NUMBER = -PROJECT_BRIEF = C++ Library +PROJECT_BRIEF = +PROJECT_LOGO = PROJECT_LOGO = -PROJECT_LOGO = images/LogoForDocumentation.png OUTPUT_DIRECTORY = $(DOXYGEN_OUTPUT_DIRECTORY) CREATE_SUBDIRS = NO ALLOW_UNICODE_NAMES = NO @@ -27,7 +27,6 @@ INHERIT_DOCS = YES SEPARATE_MEMBER_PAGES = NO TAB_SIZE = 4 ALIASES = -TCL_SUBST = OPTIMIZE_OUTPUT_FOR_C = NO OPTIMIZE_OUTPUT_JAVA = NO OPTIMIZE_FOR_FORTRAN = NO @@ -219,7 +218,7 @@ EXTRA_SEARCH_MAPPINGS = #--------------------------------------------------------------------------- GENERATE_LATEX = NO LATEX_OUTPUT = latex -LATEX_CMD_NAME = latex +LATEX_CMD_NAME = MAKEINDEX_CMD_NAME = makeindex COMPACT_LATEX = NO PAPER_TYPE = a4 @@ -260,7 +259,7 @@ MAN_LINKS = NO # Configuration options related to the XML output #--------------------------------------------------------------------------- GENERATE_XML = NO -XML_OUTPUT = temp +XML_OUTPUT = xml XML_PROGRAMLISTING = YES #--------------------------------------------------------------------------- @@ -304,13 +303,11 @@ GENERATE_TAGFILE = ALLEXTERNALS = NO EXTERNAL_GROUPS = YES EXTERNAL_PAGES = YES -PERL_PATH = /usr/bin/perl #--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- CLASS_DIAGRAMS = NO -MSCGEN_PATH = DIA_PATH = HIDE_UNDOC_RELATIONS = YES HAVE_DOT = YES From c45231984db2278c8394a4aa89a6a508e38df982 Mon Sep 17 00:00:00 2001 From: John Freeman Date: Wed, 1 Apr 2020 16:17:30 -0500 Subject: [PATCH 13/13] Rename Doxygen Workflow --- .github/workflows/{main.yml => doxygen.yml} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename .github/workflows/{main.yml => doxygen.yml} (91%) diff --git a/.github/workflows/main.yml b/.github/workflows/doxygen.yml similarity index 91% rename from .github/workflows/main.yml rename to .github/workflows/doxygen.yml index 83fc1a87583..7a21548bf0d 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/doxygen.yml @@ -1,4 +1,4 @@ -name: Build and publish documentation +name: Build and publish Doxygen documentation on: push: branches: