Merge pull request #8 from hadriansecurity/docs

Docs

.github/workflows/publish_docs.yaml

@@ -0,0 +1,60 @@
+name: Build & Publish Docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build_and_test:
+    name: Build and publish docs
+    runs-on: ubuntu-24.04
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v2
+        with:
+          path: src/
+          submodules: recursive
+
+      - name: Install prerequisites
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential \
+                            git \
+                            cmake \
+                            ninja-build \
+                            python3 \
+                            python3-sphinx \
+                            python3-sphinx-design \
+                            python3-breathe \
+                            python3-exhale \
+                            python3-sphinx-rtd-theme
+
+      - name: Make build dir
+        run: mkdir src/build
+
+      - name: Generate build files
+        run: cmake -S src/ -B src/build -DCMAKE_GENERATOR=Ninja -DCMAKE_BUILD_TYPE=Debug -DNIC_TYPE=AF_XDP -DBUILD_DOCS=ON -DBUILD_SANICDNS=OFF
+
+      - name: Build docs
+        run: ninja -C src/build Sphinx
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'src/build/docs/sphinx/html'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -44,3 +44,4 @@ compile_commands.json
 
 # Generated files
 include/version.h
+/docs/source/api/**

CMakeLists.txt

@@ -12,7 +12,24 @@ set(CMAKE_GENERATOR Ninja)
 option(OPTIMIZE_FOR_NATIVE "Build with -march=native" OFF)
 option(FORCE_COLORED_OUTPUT "Always produce ANSI-colored output (GNU/Clang only)." FALSE)
 option(BUILD_STATIC "Build a statically linked executable" OFF)
-option(BUILD_TESTS "Build a statically linked executable" OFF)
+option(BUILD_TESTS "Build the tests" OFF)
+option(BUILD_DOCS "Build the documentation" OFF)
+option(BUILD_SANICDNS "Build sanicdns" ON)
+
+# Path Definitions
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake/modules/")
+
+###############################################################################
+## documentation ##############################################################
+###############################################################################
+
+if(BUILD_DOCS)
+    add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/docs)
+endif()
+
+if(NOT BUILD_SANICDNS)
+    return()
+endif()
 
 if (${BUILD_STATIC})
     message("Building statically linked executable")
@@ -29,9 +46,6 @@ endif()
 
 add_definitions(-DSPDLOG_NO_EXCEPTIONS)
 
-# Path Definitions
-list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake/modules/")
-
 # Compiler Flags
 set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -mssse3 -msse4.2")
 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Werror -mssse3 -msse4.2")
@@ -159,4 +173,4 @@ elseif("${NIC_TYPE}" STREQUAL "I40E")
 	target_compile_definitions("${PROJ_NAME}_libs" PUBLIC NIC_I40E)
 else()
 	message(FATAL_ERROR "Invalid NIC type detected: ${NIC_TYPE}")
-endif()
+endif()

cmake/modules/FindSphinx.cmake

@@ -0,0 +1,11 @@
+#Look for an executable called sphinx-build
+find_program(SPHINX_EXECUTABLE
+             NAMES sphinx-build
+             DOC "Path to sphinx-build executable")
+
+include(FindPackageHandleStandardArgs)
+
+#Handle standard arguments to find_package like REQUIRED and QUIET
+find_package_handle_standard_args(Sphinx
+                                  "Failed to find sphinx-build executable"
+                                  SPHINX_EXECUTABLE)

docs/CMakeLists.txt

@@ -0,0 +1,80 @@
+find_package(Sphinx REQUIRED)
+find_package(Doxygen REQUIRED)
+find_program(BREATHE_APIDOC_EXECUTABLE "breathe-apidoc")
+
+# set input and output files
+set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
+
+# Define where Doxygen outputs the XML files
+set(
+    DOXYGEN_INPUT_DIR
+    "${CMAKE_SOURCE_DIR}/src ${CMAKE_SOURCE_DIR}/include ${CMAKE_SOURCE_DIR}/utils"
+    )
+
+# request to configure the file
+configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
+message("Doxygen build started")
+
+# copy the Google Cloud docs config to the build directory
+# so Github can upload the documentation
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/app.yaml ${CMAKE_CURRENT_BINARY_DIR}/app.yaml COPYONLY)
+
+# Remove old API docs folder
+file(REMOVE_RECURSE ${CMAKE_CURRENT_SOURCE_DIR}/api/)
+
+add_custom_target(doxygen_generate ALL
+    COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    DEPENDS ${DOXYGEN_OUT}
+    COMMENT "Generating API documentation with Doxygen"
+    VERBATIM
+)
+
+set(SPHINX_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/source)
+set(SPHINX_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
+set(SPHINX_INDEX_FILE ${SPHINX_BUILD_DIR}/html/index.html)
+set(BREATHE_XML_DIR "${DOXYGEN_OUTPUT_DIR}/xml")
+set(SPHINX_CONFIG_FILE "${SPHINX_SOURCE_DIR}/conf.py")
+
+# Gather all Sphinx source files
+file(GLOB_RECURSE SPHINX_SOURCE_FILES
+    "${SPHINX_SOURCE_DIR}/*.rst"
+    "${SPHINX_SOURCE_DIR}/*.py"
+    "${SPHINX_SOURCE_DIR}/*.md"
+)
+
+# Gather all images to force a rebuild on change
+file(GLOB_RECURSE IMAGES
+    "${SPHINX_SOURCE_DIR}/*.svg"
+)
+
+add_custom_command(
+    OUTPUT "${SPHINX_BUILD_DIR}/html/index.html"
+    # COMMAND "${BREATHE_APIDOC_EXECUTABLE}" -f -o "${SPHINX_SOURCE_DIR}/api" "${BREATHE_XML_DIR}"
+    COMMAND "${SPHINX_EXECUTABLE}" -b html "${SPHINX_SOURCE_DIR}" "${SPHINX_BUILD_DIR}/html"
+    DEPENDS "${SPHINX_CONFIG_FILE}" ${SPHINX_SOURCE_FILES} ${IMAGES} doxygen_generate
+    COMMENT "Generating Sphinx HTML documentation"
+    VERBATIM
+)
+
+# Only regenerate Sphinx when:
+# - Doxygen has rerun
+# - Our doc files have been updated
+# - The Sphinx config has been updated
+# add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
+#     COMMAND 
+#     ${SPHINX_EXECUTABLE} -b html
+#     # Tell Breathe where to find the Doxygen output
+#     -Dbreathe_projects.SanicDNS=${DOXYGEN_OUTPUT_DIR}/xml
+#     ${SPHINX_SOURCE_DIR} ${SPHINX_BUILD_DIR}
+#     WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+#     DEPENDS
+#     ${SPHINX_SOURCES}
+#     ${DOXYGEN_INDEX_FILE}
+#     MAIN_DEPENDENCY ${SPHINX_SOURCE_DIR}/conf.py
+#     COMMENT "Generating documentation with Sphinx")
+
+# Nice named target so we can run the job easily
+add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})