diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml new file mode 100644 index 00000000000..7a21548bf0d --- /dev/null +++ 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 diff --git a/Builds/CMake/RippledDocs.cmake b/Builds/CMake/RippledDocs.cmake index be964a56049..b168b8d0154 100644 --- 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 () 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 dd33d95e647..d716ca21315 100644 --- 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 diff --git a/docs/source.dox b/docs/Doxyfile similarity index 77% rename from docs/source.dox rename to docs/Doxyfile index fb2fa12ff6e..48a0b5d1e1a 100644 --- a/docs/source.dox +++ b/docs/Doxyfile @@ -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 diff --git a/docs/README.md b/docs/README.md index 04e25775273..3345ee828f3 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/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. + + +## Configure + +You should set these environment variables: -## Do it +- `DOXYGEN_OUTPUT_DIRECTORY` +- `DOXYGEN_PLANTUML_JAR_PATH` -### all platforms +## 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`. 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