Extend doxygen and CI config for dev documentation generation

.github/workflows/dev-docs.yml

@@ -0,0 +1,55 @@
+name: zecale-ci-dev-docs
+
+on:
+  push:
+    branches: [ develop ]
+
+jobs:
+  build-grpc:
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        submodules: recursive
+    - name: Cache grpc
+      uses: actions/cache@v2
+      with:
+        key: grpc-1.31.x-${{ runner.os }}
+        path: depends/zeth/depends/grpc
+    - name: Build grpc
+      run: |
+        pushd depends/zeth
+        if ! [ -d depends/grpc ] ; then scripts/install-grpc /usr v1.31.x ; fi
+        popd
+
+  build-documentation:
+    runs-on: ubuntu-20.04
+    needs: build-grpc
+    steps:
+    - name: Checkout repository and install submodules
+      uses: actions/checkout@v2
+      with:
+        submodules: recursive
+    - name: Cache grpc
+      uses: actions/cache@v2
+      with:
+        key: grpc-1.31.x-${{ runner.os }}
+        path: depends/zeth/depends/grpc
+    - name: Install dependencies
+      run: |
+        sudo apt update -y
+        pushd depends/zeth
+        INSTALL_ONLY=1 scripts/install-grpc /usr v1.31.x
+        popd
+        sudo apt install -y doxygen graphviz
+    - name: Generate documentation
+      run: scripts/ci build_docs
+    - name: GH Pages Deployment
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./build/docs/html/
+        enable_jekyll: false
+        allow_empty_commit: false
+        force_orphan: true
+        publish_branch: doxy-gh-pages

Doxyfile.in

@@ -32,7 +32,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "Zecale - Clearmatics Technologies LTD"
+PROJECT_NAME           = "Zecale - Reconciling Privacy and Scalability on Smart-Contract Chains"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
@@ -44,7 +44,7 @@ PROJECT_NUMBER         = @ZECALE_VERSION_MAJOR@.@ZECALE_VERSION_MINOR@
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          = "Zecale: Reconcialiting Privacy and Scalability on Ethereum"
+PROJECT_BRIEF          = "Reference implementation of the Zecale protocol by Clearmatics"
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55
@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = @CMAKE_CURRENT_BINARY_DIR@/doc_doxygen/
+OUTPUT_DIRECTORY       = @CMAKE_CURRENT_BINARY_DIR@/docs/
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -780,8 +780,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/libzecale/ \
-                         @CMAKE_CURRENT_SOURCE_DIR@/aggregator_server
+INPUT                  = @CMAKE_SOURCE_DIR@
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -842,7 +841,11 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS       = */env/* \
+                         */node_modules/* \
+                         */tests/* \
+                         */depends/* \
+                         */build/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -935,7 +938,9 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE =
+INPUT += @CMAKE_SOURCE_DIR@/README_doxygen.md
+FILE_PATTERNS += *.md
+USE_MDFILE_AS_MAINPAGE = @CMAKE_SOURCE_DIR@/README_doxygen.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing
@@ -1194,7 +1199,7 @@ HTML_COLORSTYLE_GAMMA  = 80
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_TIMESTAMP         = NO
+HTML_TIMESTAMP         = YES
 
 # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML
 # documentation will contain sections that can be hidden and shown after the
@@ -2284,7 +2289,7 @@ INCLUDED_BY_GRAPH      = YES
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-CALL_GRAPH             = NO
+CALL_GRAPH             = YES
 
 # If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller
 # dependency graph for every global function or class method.
@@ -2296,7 +2301,7 @@ CALL_GRAPH             = NO
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-CALLER_GRAPH           = NO
+CALLER_GRAPH           = YES
 
 # If the GRAPHICAL_HIERARCHY tag is set to YES then doxygen will graphical
 # hierarchy of all classes instead of a textual one.

README_doxygen.md

@@ -0,0 +1,7 @@
+# Introduction
+
+This is the developer documentation of the reference implementation of Zecale, an experimental privacy-preserving scalability solution for EVM-based chains.
+
+The software is an open source project and all community contributions are welcomed. The project is released under the LGPL-3.0 license.
+
+See https://github.com/clearmatics/zecale for further information about the project.

cmake/documentation.cmake

@@ -22,7 +22,7 @@ message("Doxygen build started")
 
 # The option ALL allows to build the docs together with the application
 add_custom_target(
-  doc_doxygen
+  build_docs
   ALL
   COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
@@ -37,6 +37,6 @@ endif()
 
 add_custom_target(
   docs
-  COMMAND ${XDG_OPEN} ${CMAKE_CURRENT_BINARY_DIR}/doc_doxygen/html/index.html
-  DEPENDS doc_doxygen
+  COMMAND ${XDG_OPEN} ${CMAKE_CURRENT_BINARY_DIR}/docs/html/index.html
+  DEPENDS build_docs
 )

scripts/ci

@@ -145,6 +145,16 @@ function build() {
     fi
 }
 
+function build_docs() {
+    cpp_build_setup
+
+    mkdir -p build
+    pushd build
+    cmake -DGEN_DOC=ON ..
+    make build_docs
+    popd
+}
+
 function ci_setup() {
 
     if [ "${platform}" == "Darwin" ] ; then