Fix Doxygen build

2025-11-04 10:45:50 +00:00 · 2020-03-16 11:04:06 -05:00
parent 758a3792eb
commit 3e9cff9287
7 changed files with 150 additions and 129 deletions
--- a/.github/workflows/doxygen.yml
+++ b/.github/workflows/doxygen.yml
@@ -0,0 +1,23 @@
+name: Build and publish Doxygen 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
--- a/Builds/CMake/RippledDocs.cmake
+++ b/Builds/CMake/RippledDocs.cmake
@@ -3,29 +3,82 @@
 #]===================================================================]

 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}/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
+  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 (WARNING "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}")
+if (is_multiconfig)
+  set_property (
+    SOURCE ${dependencies}
+    APPEND PROPERTY
+    HEADER_FILE_ONLY true)
 endif ()
--- 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"
--- a/docs/Dockerfile
+++ b/docs/Dockerfile
@@ -26,6 +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

-CMD cd /opt/rippled/docs && doxygen source.dox
+ENV DOXYGEN_OUTPUT_DIRECTORY=html
+CMD cd /opt/rippled && doxygen docs/Doxyfile
--- a/docs/source.dox
+++ b/docs/source.dox
@@ -4,10 +4,10 @@
 DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = "rippled"
 PROJECT_NUMBER         =
-PROJECT_BRIEF          = C++ Library
+PROJECT_BRIEF          =
 PROJECT_LOGO           =
-PROJECT_LOGO           = images/LogoForDocumentation.png
-OUTPUT_DIRECTORY       =
+PROJECT_LOGO           =
+OUTPUT_DIRECTORY       = $(DOXYGEN_OUTPUT_DIRECTORY)
 CREATE_SUBDIRS         = NO
 ALLOW_UNICODE_NAMES    = NO
 OUTPUT_LANGUAGE        = English
@@ -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
@@ -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
@@ -35,7 +34,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
@@ -83,7 +82,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         =
@@ -104,71 +103,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 \
-    ../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 \
+    docs \
+    src/ripple \
+    src/test \
+    src/README.md \
+    README.md \
+    RELEASENOTES.md \


 INPUT_ENCODING         = UTF-8
-FILE_PATTERNS          =
-RECURSIVE              = NO
+FILE_PATTERNS          = *.h *.cpp *.md
+RECURSIVE              = YES
 EXCLUDE                =
 EXCLUDE_SYMLINKS       = NO
 EXCLUDE_PATTERNS       =
@@ -177,20 +122,20 @@ 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
 #---------------------------------------------------------------------------
-SOURCE_BROWSER         = NO
+SOURCE_BROWSER         = YES
 INLINE_SOURCES         = NO
 STRIP_CODE_COMMENTS    = YES
 REFERENCED_BY_RELATION = NO
@@ -213,7 +158,7 @@ IGNORE_PREFIX          =
 # Configuration options related to the HTML output
 #---------------------------------------------------------------------------
 GENERATE_HTML          = YES
-HTML_OUTPUT            = html_doc
+HTML_OUTPUT            = html
 HTML_FILE_EXTENSION    = .html
 HTML_HEADER            =
 HTML_FOOTER            =
@@ -273,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
@@ -314,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

 #---------------------------------------------------------------------------
@@ -340,7 +285,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 \
@@ -353,21 +298,20 @@ SKIP_FUNCTION_MACROS   = YES
 #---------------------------------------------------------------------------
 # Configuration options related to external references
 #---------------------------------------------------------------------------
-TAGFILES               =
+TAGFILES               = $(DOXYGEN_TAGFILES)
 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               = NO
+HAVE_DOT               = YES
+# DOT_NUM_THREADS = 0 means 1 for every processor.
 DOT_NUM_THREADS        = 0
 DOT_FONTNAME           = Helvetica
 DOT_FONTSIZE           = 10
@@ -386,11 +330,11 @@ 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           =
-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
--- 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/source.dox`. Note that the `INPUT` paths are
-relative to the `docs/` directory.
-
 ## Install Dependencies

 ### Windows
@@ -30,32 +24,38 @@ 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:

 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.

-## Do it

-### all platforms
+## Configure
+
+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 source.dox
+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`.
--- a/src/ripple/app/ledger/impl/InboundLedgers.cpp
+++ b/src/ripple/app/ledger/impl/InboundLedgers.cpp
@@ -64,6 +64,7 @@ public:
    {
    }

+    /** @callgraph */
    std::shared_ptr<Ledger const>
    acquire(uint256 const& hash, std::uint32_t seq,
        InboundLedger::Reason reason) override