Add docs (#16)

* Add docs

* Fetch doxygen css files directly from GH repo

* Add link for LICENSE

Author: Hind-M

.github/workflows/docs.yaml

@@ -0,0 +1,58 @@
+name: doxygen-docs
+on: [push, pull_request]
+
+defaults:
+  run:
+    shell: bash -e -l {0}
+jobs:
+  build_docs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Set conda environment
+      uses: mamba-org/setup-micromamba@main
+      with:
+        environment-name: myenv
+        environment-file: environment-dev.yml
+        init-shell: bash
+        cache-downloads: true
+
+    - name: Configure using CMake
+      run: cmake -G Ninja -Bbuild -DCMAKE_BUILD_TYPE:STRING=Debug -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DBUILD_DOCS=ON 
+
+    - name: Build docs target
+      run: cmake --build build --target docs
+
+    - name: Upload Pages artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: build/docs/html
+
+
+  deploy:
+    # only run on main branch
+    if: github.ref == 'refs/heads/main' && github.repository == 'QuantStack/sparrow-ipc'
+
+    # Add a dependency to the build job
+    needs: build_docs
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      contents: read   # to read the Pages artifact
+      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 }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4 # or specific "vX.X.X" version tag for this action

CMakeLists.txt

@@ -44,6 +44,9 @@ endif()
 OPTION(SPARROW_IPC_BUILD_TESTS "Build sparrow-ipc test suite" OFF)
 MESSAGE(STATUS "🔧 Build tests: ${SPARROW_IPC_BUILD_TESTS}")
 
+OPTION(BUILD_DOCS  "Build sparrow-ipc documentation" OFF)
+MESSAGE(STATUS "🔧 Build docs: ${BUILD_DOCS}")
+
 set(SPARROW_IPC_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/include)
 set(SPARROW_IPC_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/src)
 
@@ -153,8 +156,17 @@ target_link_libraries(sparrow-ipc
 
 add_dependencies(sparrow-ipc generate_flatbuffers_headers)
 
+# Tests
+# =====
 if(SPARROW_IPC_BUILD_TESTS)
     message(STATUS "🧪 Create tests targets")
     enable_testing()
     add_subdirectory(tests)
 endif()
+
+# Docs
+# ====
+if(BUILD_DOCS)
+    message(STATUS "📚 Create docs targets")
+    add_subdirectory(docs)
+endif()

conanfile.py

@@ -18,16 +18,18 @@ class SparrowIPCRecipe(ConanFile):
     topics = ("arrow", "apache arrow", "columnar format", "dataframe", "ipc", "serialization", "deserialization", "flatbuffers")
     package_type = "library"
     settings = "os", "arch", "compiler", "build_type"
-    exports_sources = "include/*", "src/*", "cmake/*", "CMakeLists.txt", "LICENSE"
+    exports_sources = "include/*", "src/*", "cmake/*", "docs/*", "CMakeLists.txt", "LICENSE"
     options = {
         "shared": [True, False],
         "fPIC": [True, False],
         "build_tests": [True, False],
+        "generate_documentation": [True, False],
     }
     default_options = {
         "shared": False,
         "fPIC": True,
         "build_tests": False,
+        "generate_documentation": False,
     }
 
     _flatbuffers_version = "24.12.23"
@@ -48,6 +50,8 @@ def requirements(self):
 
     def build_requirements(self):
         self.tool_requires("cmake/[>=3.28.1 <4.2.0]")
+        if self.options.get_safe("generate_documentation"):
+            self.tool_requires("doxygen/[>=1.9.4 <2.0.0]", options={"enable_app": "True"})
         self.tool_requires(f"flatbuffers/{self._flatbuffers_version}")
 
     @property
@@ -84,6 +88,7 @@ def generate(self):
         tc = CMakeToolchain(self)
         tc.variables["SPARROW_IPC_BUILD_SHARED"] = self.options.shared
         tc.variables["SPARROW_IPC_BUILD_TESTS"] = self.options.build_tests
+        tc.variables["BUILD_DOCS"] = self.options.generate_documentation
         tc.generate()
 
     def build(self):

docs/CMakeLists.txt

@@ -0,0 +1,41 @@
+find_package(Doxygen REQUIRED)
+
+set(DOXYGEN_AWESOME_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen-awesome-css)
+file(MAKE_DIRECTORY ${DOXYGEN_AWESOME_DIR})
+
+set(BASE_URL "https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/v2.3.4")
+
+set(FILES_TO_DOWNLOAD
+    LICENSE
+    doxygen-awesome-darkmode-toggle.js
+    doxygen-awesome-fragment-copy-button.js
+    doxygen-awesome-interactive-toc.js
+    doxygen-awesome-paragraph-link.js
+    doxygen-awesome-sidebar-only-darkmode-toggle.css
+    doxygen-awesome-sidebar-only.css
+    doxygen-awesome-tabs.js
+    doxygen-awesome.css
+)
+
+foreach(FILE ${FILES_TO_DOWNLOAD})
+    if(NOT EXISTS ${DOXYGEN_AWESOME_DIR}/${FILE})
+        message(STATUS "Downloading ${FILE}")
+        file(DOWNLOAD ${BASE_URL}/${FILE} ${DOXYGEN_AWESOME_DIR}/${FILE} STATUS status)
+    endif()
+endforeach()
+
+set(DOXYGEN_AWESOME_CSS_PATH "${DOXYGEN_AWESOME_DIR}/doxygen-awesome.css")
+
+# Configure the doxygen.in file
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
+
+# Add a target to generate API documentation with Doxygen
+add_custom_target(docs
+    COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    COMMENT "Generating API documentation with Doxygen"
+    VERBATIM
+)
+
+# Add install capabilities
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html DESTINATION share/doc)