Merge pull request #3 from sjinks/add-docs

docs: Doxygen documentation

.clang-format

@@ -140,7 +140,7 @@ PackConstructorInitializers: BinPack
 PointerAlignment: Left
 QualifierAlignment: Leave
 ReferenceAlignment: Pointer
-ReflowComments: true
+ReflowComments: false
 RemoveBracesLLVM: false
 RemoveSemicolon: false
 RequiresClausePosition: OwnLine

.github/actions/install-dependencies/action.yml

@@ -7,4 +7,4 @@ runs:
       shell: bash
       run: |
         sudo apt-get update
-        sudo apt-get install -y libgmock-dev libgtest-dev nlohmann-json3-dev valgrind llvm gcovr
+        sudo apt-get install -y libgmock-dev libgtest-dev nlohmann-json3-dev valgrind llvm gcovr doxygen graphviz

.github/workflows/apidocs.yml

@@ -0,0 +1,49 @@
+name: Deploy API Docs to Pages
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Deploy
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the source code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Install dependencies
+        uses: ./.github/actions/install-dependencies
+
+      - name: Generate API Docs
+        run: |
+          cmake -B build
+          cmake --build build --target doxygen
+
+      - name: Setup Pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
+        with:
+          path: apidocs
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

.gitignore

@@ -1,4 +1,5 @@
 /.cache/
 /.vscode/
+/apidocs/
 /build/
 /build-*/

CMakeLists.txt

@@ -4,6 +4,7 @@ set(EXPORT_COMPILE_COMMANDS ON)
 
 option(BUILD_SHARED_LIBS "Build shared libraries" OFF)
 option(BUILD_TESTS "Build tests" ON)
+option(BUILD_DOCS "Build documentation" ON)
 option(ENABLE_MAINTAINER_MODE "Enable maintainer mode" OFF)
 
 project(
@@ -35,6 +36,31 @@ if(BUILD_TESTS)
     endif()
 endif()
 
+if(BUILD_DOCS)
+    include(FindDoxygen)
+    find_package(Doxygen)
+    if(NOT DOXYGEN_FOUND)
+        message(WARNING "Doxygen not found, documentation will not be built")
+        set(BUILD_DOCS OFF)
+    else()
+        if(TARGET Doxygen::dot)
+            set(HAVE_DOT "YES")
+        else()
+            set(HAVE_DOT "NO")
+        endif()
+        configure_file("${CMAKE_SOURCE_DIR}/cmake/Doxyfile.in" "${CMAKE_BINARY_DIR}/Doxyfile" @ONLY)
+        add_custom_target(
+            doxygen
+            COMMAND Doxygen::doxygen "${CMAKE_BINARY_DIR}/Doxyfile"
+            COMMAND "${CMAKE_COMMAND}" -E copy_directory "${CMAKE_BINARY_DIR}/docs/html/" "${CMAKE_SOURCE_DIR}/apidocs"
+            WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+            COMMENT "Generating API documentation with Doxygen"
+            DEPENDS ${PROJECT_NAME}
+            VERBATIM
+        )
+    endif()
+endif()
+
 if(CMAKE_COMPILER_IS_GNU OR CMAKE_COMPILER_IS_CLANG)
     set(CMAKE_CXX_FLAGS_ASAN "-O1 -g -fsanitize=address -fno-omit-frame-pointer -fno-optimize-sibling-calls")
     set(CMAKE_CXX_FLAGS_LSAN "-O1 -g -fsanitize=leak -fno-omit-frame-pointer -fno-optimize-sibling-calls")
@@ -184,7 +210,7 @@ install(
     RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
     LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
     ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
-    FILE_SET HEADERS DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/${PROJECT_NAME}"
+    FILE_SET HEADERS DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/wwa/jsonrpc"
 )
 
 install(

README.md

@@ -0,0 +1,71 @@
+# JSON RPC
+
+[![Build and Test](https://github.com/sjinks/jsonrpc-cpp/actions/workflows/ci.yml/badge.svg)](https://github.com/sjinks/jsonrpc-cpp/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/sjinks/jsonrpc-cpp/actions/workflows/codeql.yml/badge.svg)](https://github.com/sjinks/jsonrpc-cpp/actions/workflows/codeql.yml)
+
+JSON-RPC 2.0 library for C++
+
+## Introduction
+
+This library provides a robust implementation of the JSON-RPC 2.0 protocol for C++. It allows you to easily handle JSON-RPC requests, and manage responses.
+
+## Features
+
+- Full support for JSON-RPC 2.0
+- Easy-to-use API
+- Error handling and validation
+
+## Installation
+
+To install the library, follow these steps:
+
+1. Clone the repository:
+    ```sh
+    git clone https://github.com/sjinks/jsonrpc-cpp.git
+    cd jsonrpc-cpp
+    ```
+
+2. Build the project using CMake:
+    ```sh
+    cmake -B build -DCMAKE_BUILD_TYPE=Release
+    cmake --build build
+    ```
+
+3. Install the library:
+    ```sh
+    cmake --install build # In Linux, you may have to use `sudo`
+    ```
+
+## Usage
+
+```cpp
+#include <wwa/jsonrpc/dispatcher.h>
+
+class my_server {
+public:
+    my_server()
+    {
+        this->m_dispatcher.add("add", &my_server::add, this);
+    }
+
+    void handle_request()
+    {
+        // Read the request somehow
+        const std::string input = read_request();
+
+        const std::string response = this->m_dispatcher->parse_and_process_request(input);
+        if (!response.empty()) {
+            // Send the response
+            send_response(response);
+        }
+    }
+
+private:
+    wwa::json_rpc::dispatcher m_dispatcher;
+
+    int add(int a, int b)
+    {
+        return a + b;
+    }
+};
+```