change to rst for documentation

YanzhaoW · Nov 22, 2024 · 0b0e352 · 0b0e352
1 parent 9c028d8
commit 0b0e352
Show file tree

Hide file tree

Showing 13 changed files with 303 additions and 201 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,16 +1,19 @@
 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
     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)
+include(sphinx_setup)
+include(install_config)
+include(project_config)
+include(check_compilers)
 
 set(CMAKE_CXX_STANDARD 23)
 set(CMAKE_CXX_EXTENSIONS ON)
@@ -21,7 +24,7 @@ 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)

diff --git a/README.md → README.rst b/README.md → README.rst
@@ -1,40 +1,55 @@
-# srs-daq - A data acquisition program for SRS FEC & VMM3
+======================================================================
+srs-daq - A data acquisition program for SRS FEC & VMM3
+======================================================================
+
+.. |codacyBadge| image:: https://app.codacy.com/project/badge/Grade/7e8c956af1bc46c7836524f1ace32c11
+   :alt: Codacy badge
+   :target: https://app.codacy.com/gh/YanzhaoW/srs-daq/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade
+.. |ciPipeline| image:: https://github.com/YanzhaoW/srs-daq/actions/workflows/ci.yml/badge.svg?branch=dev
+   :alt: ci pipeline
+   :target: https://github.com/YanzhaoW/srs-daq/actions?query=branch%3Adev
+.. |githubReleases| image:: https://img.shields.io/github/release/YanzhaoW/srs-daq.svg
+   :alt: github releases
+   :target: https://github.com/YanzhaoW/srs-daq/releases
+.. |license| image:: https://img.shields.io/badge/License-MIT-yellow.svg
+   :alt: License: MIT
+   :target: https://opensource.org/licenses/MIT
+
+Introduction
+=================================================
 
-[![Codacy Badge](https://app.codacy.com/project/badge/Grade/7e8c956af1bc46c7836524f1ace32c11)](https://app.codacy.com/gh/YanzhaoW/srs-daq/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
-[![CI pipeline](https://github.com/YanzhaoW/srs-daq/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/YanzhaoW/srs-daq/actions?query=branch%3Adev)
-[![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)
+srs-daq is an asynchronous data IO program for SRS system. It communicates with the SRS system through the UDP socket with different commands to, for example, start or stop the data transferring from the system. Data sent from the SRS system is then analyzed in the program in different stages, such as the deserialization, monitoring, data conversion and writing to different files or sockets. There are 4 types of output formats supported: binary file, root file (require ROOT), JSON file and UDP socket. Binary file can store either **as-is** data sent from the SRS system or the Google's Protobuf binary. UDP socket can only send the Google's Protobuf binary due to its easy deserialization.
 
-## Introduction
+Technical information about classes and functions can be found in this `Doxygen documentation <https://yanzhaow.github.io/srs-daq/>`_.
 
-srs-daq is an asynchronous data IO program for SRS system. It communicates with the SRS system through the UDP socket with different commands to, for example, start or stop the data transferring from the system. Data sent from the SRS system is then analyzed in the program in different stages, such as the deserialization, monitoring, data conversion and writing to different files or sockets. There are 4 types of output formats supported: binary file, root file (require ROOT), JSON file and UDP socket. Binary file can store either **as-is** data sent from the SRS system or the Google's Protobuf binary. UDP socket can only send the Google's Protobuf binary due to its easy deserialization.
+Download the project
+----------------------------------------
 
-Technical information about classes and functions can be found in this [Doxygen documentation](https://yanzhaow.github.io/srs-daq/).
+Please visit the `release page <https://github.com/YanzhaoW/srs-daq/releases>`_ and download the latest release for your operating system:
 
-## Download the project
+.. code-block:: bash
 
-Please visit the [release page](https://github.com/YanzhaoW/srs-daq/releases) and download the latest release for your operating system:
+  wget [download-link]
+  tar -xvzf [download-file]
 
-```bash
-wget [download-link]
-tar -xvzf [download-file]
-```
 After unzipping the downloaded file, a new folder `srs-daq` 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.
+.. note::
+  If the ROOT support is needed, please install the same ROOT version used in the download link.
 
-## srs_control - The main program
+srs_control - The main program
+=================================================
 
 Go to `srs-daq/bin` directory and run
 
-```bash
-./srs_control [-p DATA_PRINT_OPTION] [-v LOG_LEVEL] [-h]
-```
+.. code-block:: bash
+
+  ./srs_control [-p DATA_PRINT_OPTION] [-v LOG_LEVEL] [-h]
 
-### Run-time options
+Run-time options
+-------------------------------------------
 
 - `-h` or `--help`: print the help message.
 - `-v` or `--version`: show the current version.
@@ -47,7 +62,8 @@ Go to `srs-daq/bin` directory and run
   - 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
+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):
 
@@ -62,47 +78,54 @@ Users have to use the correct file extensions to enable the corresponding output
 
 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"
-```
+.. code-block:: bash
 
-## Usage of other executables
+  ./srs_control -o "output1.root" -o "output2.root" \
+                -o "output.bin" -o "output.binpb" \
+                -o "output.json" -o "localhost:9999"
 
-### `srs_check_binpb`
+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
-```
+.. code-block:: bash
+
+  ./srs_check_binpb -f filename.binpb
 
-### `srs_check_udp`
+`srs_check_udp`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The executable checks the data output from a UDP socket.
 
-```bash
-./srs_check_udp --port [port number] --ip "localhost"
-```
+.. code-block:: bash
+
+  ./srs_check_udp --port [port number] --ip "localhost"
 
-## Usage of SRS library
+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
+Custom configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 To be added ...
 
-## Acknowledgments
+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).
+- 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
+TODO list
+-------------------------------------------
 
 - unit tests
 - Control/monitoring for SRS FEC & VMM3a hybrids

diff --git a/cmake/option_settings.cmake b/cmake/option_settings.cmake
@@ -2,3 +2,7 @@ option(USE_ROOT "Force to use ROOT dependency." OFF)
 option(NO_ROOT "Disable the usage of ROOT dependency." OFF)
 option(BUILD_STATIC "Enable static linking of libstdc++." OFF)
 option(ENABLE_TEST "Enable testing framework of the project." ON)
+
+set(SPHINX_BUILDER
+    "html"
+    CACHE STRING "Set the builder for sphnix-build.")
diff --git a/cmake/sphinx_setup.cmake b/cmake/sphinx_setup.cmake
@@ -0,0 +1,7 @@
+configure_file(${CMAKE_SOURCE_DIR}/doc/conf.py.in ${CMAKE_BINARY_DIR}/conf.py)
+
+add_custom_target(
+    sphinx
+    COMMENT "launching sphinx build"
+    COMMAND sphinx-build --build ${SPHINX_BUILDER} --write-all -c ${CMAKE_BINARY_DIR}
+            ${CMAKE_SOURCE_DIR}/doc ${CMAKE_BINARY_DIR}/sphinx)
diff --git a/doc/build_source.md b/doc/build_source.md
diff --git a/doc/build_source.rst b/doc/build_source.rst
@@ -0,0 +1,83 @@
+###################################
+Build the project from source
+###################################
+
+Prerequisites
+##############################
+
+- C++ compiler (choose either one below)
+  - gcc <span>&#8805;</span> 14.3.
+  - clang <span>&#8805;</span> 18
+- oneTBB
+- **(Optional)** ROOT <span>&#8805;</span> 6.32
+
+- (mini) Conda. See [this instruction](install_conda.md) to install miniconda quickly.
+
+.. warning::
+  DO NOT USE Conda to install ROOT. Use latest compiler to install ROOT from the source.
+
+Installation
+##############################
+
+Step 1: Clone the latest version
+------------------------------------
+
+.. code-block:: bash
+
+  git clone -b [latest version] https://github.com/YanzhaoW/srs-daq.git
+  cd srs-daq
+  git submodule update --init
+
+Step 2: Activate the Conda environment
+-------------------------------------------
+
+.. code-block:: bash
+
+  conda env create -f environment.yml
+  conda activate srs
+
+Step 3: Build the project
+------------------------------------
+
+**Make sure conda environment `srs` is activated.**
+
+.. code-block:: bash
+
+  cmake --workflow --preset default
+
+or
+
+.. code-block:: bash
+
+  cmake --preset default -DCMAKE_INSTALL_PREFIX=[/usr/local] [optional settings]
+  cmake --build ./build --target install -- -j[nproc]
+
+
+Following CMake preset optional settings are available:
+
+- `-DUSE_ROOT=`
+  - `OFF` or `FALSE` (default). The program would only compile with ROOT if ROOT exists. 
+  - `ON` or `TRUE`. CMake configuration will fail if `ROOT` is not found. 
+- `-DNO_ROOT=`
+  - `OFF` or `FALSE` (default). Same as `-DUSE_ROOT=OFF`.
+  - `ON` or `TRUE`. The program does NOT compiler with ROOT even if ROOT exists.
+
+For example, to disable the ROOT dependency, run the `cmake --preset` with:
+
+.. code-block:: bash
+
+  cmake --preset default . -DNO_ROOT=TRUE
+
+
+Update to the latest version
+---------------------------------
+
+srs-daq is under a continuous development. To update to the latest version, run the following git commands:
+
+.. code-block:: bash
+
+  git fetch origin
+  git checkout latest
+  git submodule update --init
+
+After this, build the project again from Step 3.
diff --git a/doc/conf.py.in b/doc/conf.py.in
@@ -0,0 +1,28 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = '@CMAKE_PROJECT_NAME@'
+copyright = '2024, Yanzhao Wang'
+author = 'Yanzhao Wang'
+release = '@CMAKE_PROJECT_VERSION@'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["myst_parser"]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+source_suffix = ['.rst', '.md', '.cpp']
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = []