ARCHIVE/xahaud
3
0
Fork 0
mirror of https://github.com/Xahau/xahaud.git synced 2025-11-04 18:55:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix Doxygen build

Browse Source
This commit is contained in:
John Freeman
2020-03-16 11:04:06 -05:00
committed by manojsdoshi
parent 758a3792eb
commit 3e9cff9287
7 changed files with 150 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
.github/workflows/doxygen.yml vendored Normal file
View File

@@ -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

101
Builds/CMake/RippledDocs.cmake
View File

@@ -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 ()

2
bin/ci/ubuntu/build-and-test.sh
View File

@@ -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"

5
docs/Dockerfile
View File

@@ -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

112
docs/source.dox → docs/Doxyfile
View File

@@ -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

35
docs/README.md
View File

@@ -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`.

1
src/ripple/app/ledger/impl/InboundLedgers.cpp
View File

@@ -64,6 +64,7 @@ public:
{
}
/** @callgraph */
std::shared_ptr<Ledger const>
acquire(uint256 const& hash, std::uint32_t seq,
InboundLedger::Reason reason) override