Generate Sphinx documentation in Github pages (#10)

- Add sphinx documentation with breathe and doxygen - Add extra workflow to generate documentation - Add preview of srs_control
YanzhaoW · Nov 25, 2024 · ba345b3 · ba345b3
2 parents 15c3a72 + d579d36
commit ba345b3
Show file tree

Hide file tree

Showing 29 changed files with 735 additions and 280 deletions.
diff --git a/.clang-tidy b/.clang-tidy
@@ -26,7 +26,6 @@ Checks: >
   modernize-*,
   performance-*,
   readability-*,
-  -hicpp-new-delete-operators,
   -modernize-use-trailing-return-type
 
 CheckOptions:

diff --git a/.github/workflows/publish_doc.yml b/.github/workflows/publish_doc.yml
@@ -0,0 +1,46 @@
+name: publish-doc
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+jobs:
+  artifact-gen:
+    runs-on: macos-15
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: 'true'
+      - name: run doxygen
+        run: |
+          brew upgrade
+          brew install doxygen graphviz cmake ninja
+          python3 -m venv venv
+          source venv/bin/activate
+          python3 -m pip install --upgrade pip
+          python3 -m pip install sphinx breathe sphinx-rtd-theme
+          cmake --workflow --preset build-doc
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: build/doc/sphinx
+          retention-days: 1
+
+  deploy-doc:
+    runs-on: macos-15
+    needs: artifact-gen
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -87,11 +87,10 @@ jobs:
         run: |
           source $PARENT_DIR/miniconda3/bin/activate
           conda activate srs
-          mkdir ${PARENT_DIR}/srs-install
-          cmake --preset ${{ matrix.preset}} -DCMAKE_INSTALL_PREFIX=${PARENT_DIR}/srs-install -DNO_ROOT=$DISABLE_ROOT
+          mkdir srs-daq
+          cmake --preset ${{ matrix.preset}} -DCMAKE_INSTALL_PREFIX="./srs-daq" -DNO_ROOT=$DISABLE_ROOT
           cmake --build ./build --target install -- -j2
-          cd ${{ env.PARENT_DIR }}
-          tar czf "srs-${{ matrix.os}}-x86-64-${{ env.TAG_NAME }}-${{ env.ROOT_TAG }}.tar.gz" srs-install
+          tar czf "srs-${{ matrix.os}}-x86-64-${{ env.TAG_NAME }}-${{ env.ROOT_TAG }}.tar.gz" "./srs-daq"
 
       - uses: actions/upload-artifact@v4
         with:

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,31 +1,41 @@
 cmake_minimum_required(VERSION 3.28)
 
-include(${CMAKE_SOURCE_DIR}/cmake/option_settings.cmake)
+list(APPEND CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake)
+
+include(option_settings)
+
 set(ENV{CMAKE_ENABLE_TEST} ${ENABLE_TEST})
 
 project(
-    srs
+    SRS-DAQ
     VERSION 0.1.1
     LANGUAGES CXX C)
 
-include(${CMAKE_SOURCE_DIR}/cmake/install_config.cmake)
-include(${CMAKE_SOURCE_DIR}/cmake/project_config.cmake)
-include(${CMAKE_SOURCE_DIR}/cmake/check_compilers.cmake)
+if(BUILD_ONLY_DOC)
+    add_subdirectory(doc)
+else()
+    if(BUILD_DOC)
+        add_subdirectory(doc)
+    endif()
+    include(install_config)
+    include(project_config)
+    include(check_compilers)
 
-set(CMAKE_CXX_STANDARD 23)
-set(CMAKE_CXX_EXTENSIONS ON)
-set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
-set(CMAKE_CXX_SCAN_FOR_MODULES OFF)
+    set(CMAKE_CXX_STANDARD 23)
+    set(CMAKE_CXX_EXTENSIONS ON)
+    set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+    set(CMAKE_CXX_SCAN_FOR_MODULES OFF)
 
-if(CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
-    list(APPEND CMAKE_CXX_FLAGS "-fexperimental-library")
-endif()
+    if(CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
+        list(APPEND CMAKE_CXX_FLAGS "-fexperimental-library")
+    endif()
 
-include(${CMAKE_SOURCE_DIR}/cmake/import_packages.cmake)
+    include(import_packages)
 
-add_subdirectory(frontend)
-add_subdirectory(backend)
-add_subdirectory(examples)
-if(ENABLE_TEST)
-    add_subdirectory(test)
+    add_subdirectory(frontend)
+    add_subdirectory(backend)
+    add_subdirectory(examples)
+    if(ENABLE_TEST)
+        add_subdirectory(test)
+    endif()
 endif()
diff --git a/CMakePresets.json b/CMakePresets.json
@@ -30,6 +30,15 @@
                 "CONAN_INSTALL_ARGS": "--build=missing;-scompiler.cppstd=gnu20",
                 "BUILD_STATIC": "ON"
             }
+        },
+        {
+            "name": "build-doc",
+            "displayName": "build-doc",
+            "description": "Documentation only build",
+            "binaryDir": "${sourceDir}/build",
+            "cacheVariables": {
+                "BUILD_ONLY_DOC": "ON"
+            }
         }
     ],
     "buildPresets": [
@@ -40,6 +49,11 @@
         {
             "name": "static",
             "configurePreset": "static"
+        },
+        {
+            "name": "build-doc",
+            "configurePreset": "build-doc",
+            "targets": "doc"
         }
     ],
     "workflowPresets": [
@@ -68,6 +82,19 @@
                     "name": "static"
                 }
             ]
+        },
+        {
+            "name": "build-doc",
+            "steps": [
+                {
+                    "type": "configure",
+                    "name": "build-doc"
+                },
+                {
+                    "type": "build",
+                    "name": "build-doc"
+                }
+            ]
         }
     ]
 }
diff --git a/README.md b/README.md
@@ -5,108 +5,15 @@
 [![Github Releases](https://img.shields.io/github/release/YanzhaoW/srs-daq.svg)](https://github.com/YanzhaoW/srs-daq/releases)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Introduction
+SRS-DAQ is a project containing a command line tool `srs_control` and additional library APIs that can be used to communicate with SRS system and interpret the received data in your own program.
 
-srs-daq is an asynchronous data IO program for SRS system.
+Please check the full documentation of this project: [SRS-DAQ documentation](<https://yanzhaow.github.io/srs-daq/>).
 
-### Included
+## `srs_control` preview
 
-- Readout of data
-- Data deserialization from SRS system
-
-## Download the project
-
-Please visit the [release page](https://github.com/YanzhaoW/srs-daq/releases) and download the latest release for your operating system:
-
-```bash
-wget [download-link]
-tar -xvzf [download-file]
-```
-After unzipping the downloaded file, a new folder `srs-install` will be put in the current folder.
-
-If your operating system is not in the download link list. Please either [build the project from source](doc/build_source.md) or create an issue to make the request.
-
-> [!IMPORTANT]  
-> If the ROOT support is needed, please install the same ROOT version used in the download link.
-
-## srs_control - The main program
-
-Go to `srs-install/bin` directory and run
-
-```bash
-./srs_control [-p DATA_PRINT_OPTION] [-v LOG_LEVEL] [-h]
-```
-
-### Run-time options
-
-- `-h` or `--help`: print the help message.
-- `-v` or `--version`: show the current version.
-- `--root-version`: show the ROOT version if used.
-- `-l` or `--log-level`: set the verbose level. Available options: "critical", "error", "warn", "info" (default), "debug", "trace", "off".
-- `-p` or `--print-mode`: set the data printing mode. Available options:
-  - speed (default): print the reading rate of received data.
-  - header: print the header message of received data.
-  - raw: print the received raw bytes.
-  - all: print all data, including header, hit and marker data, but no raw data.
-- `-o` or `--output-files`: set the file outputs (more detail below).
-
-### Data output to multiple files
-
-`srs_control` can output received data into multiple files with different types at the same time. Currently, following output types are available (or planned):
-
-- **binary**:
-  - raw data if `.lmd` or `.bin`
-  - protobuf data if `.binpb`
-- **json**. File extensions: `.json` (NOTE: JSON file could be very large)
-- **root**. File extensions: `.root` (require ROOT library)
-- **UDP socket** (protobuf + gzip). Input format: `[ip]:[port]`
-
-Users have to use the correct file extensions to enable the corresponding output types.
-
-To output the same data to multiple different output types at the same time:
-
-```bash
-./srs_control -o "output1.root" -o "output2.root" \
-              -o "output.bin" -o "output.binpb" \
-              -o "output.json" -o "localhost:9999"
-```
-
-## Usage of other executables
-
-### `srs_check_binpb`
-
-This is used for checking the contents of a Protobuf binary file.
-
-```bash
-./srs_check_binpb -f filename.binpb
-```
-
-### `srs_check_udp`
-
-The executable checks the data output from a UDP socket.
-
-```bash
-./srs_check_udp --port [port number] --ip "localhost"
-```
-
-## Usage of SRS library
-
-The program also has APIs to provide following functionality:
-
-- Convert binary `string_view` to the data structure `srs::StructData`.
-
-For more information, please check the [library usage](doc/library_usage.md).
-
-### Custom configuration
-
-To be added ...
+![Imgur](doc/media/srs_control_preview_v1.gif)
 
 ## Acknowledgments
 
 - A lot of information was used from the existing codebase of the VMM slow control software [vmmsc](https://gitlab.cern.ch/rd51-slow-control/vmmsc.git).
-
-## TODO list
-
-- unit tests
-- Control/monitoring for SRS FEC & VMM3a hybrids
-- Graphical user interface (typescript + react + websocket).
+- The understanding of the communication protocol was helped from [srslib](https://github.com/bl0x/srslib).
diff --git a/backend/srs/readers/ProtoMsgReader.hpp b/backend/srs/readers/ProtoMsgReader.hpp
@@ -11,19 +11,50 @@ namespace srs
     class ProtoMsgReader
     {
       public:
+        /**
+         * Constructor allocates the memeory for member variables
+         */
         ProtoMsgReader();
 
+        //! Deleted copy constructor
         ProtoMsgReader(const ProtoMsgReader&) = delete;
-        ProtoMsgReader(ProtoMsgReader&&) = default;
+
+        //! Deleted copy assignment
         ProtoMsgReader& operator=(const ProtoMsgReader&) = delete;
+
+        //! Default move constructor
+        ProtoMsgReader(ProtoMsgReader&&) = default;
+
+        //! Default move assignment
         ProtoMsgReader& operator=(ProtoMsgReader&&) = default;
+
+        //! Default destructor
         ~ProtoMsgReader();
 
+        /**
+         * Convert binary data to a struct (inout).
+         *
+         * @param msg The input binary data.
+         * @param struct_data The struct data to store the deserialized binary data.
+         */
         auto convert(std::string_view msg, StructData& struct_data);
+
+        /**
+         * Convert binary data to a struct, owned by ProtoMsgReader.
+         *
+         * Description.
+         *
+         * @param msg The input binary data.
+         * @return The const reference to the internal struct data.
+         *
+         */
         auto convert(std::string_view msg) -> const StructData&;
 
       private:
+        //! A converter to transform Protobuf struct to native C++ struct
         std::unique_ptr<Proto2StructConverter> proto_to_struct_converter_;
+
+        //! A converter to transform binary data to Protobuf struct
         std::unique_ptr<ProtoDeserializer> proto_deserializer_;
     };
 } // namespace srs