Doc: Update stylesheets and clean up documentations

.github/workflows/build.yml

@@ -7,59 +7,68 @@ permissions:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, macos-14]
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: recursive
 
-      - name: Set up Python
-        uses: actions/setup-python@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
         with:
-          python-version: "3.10"
+          version: "latest"
 
-      - name: Init submodules
-        run: git submodule update --init --recursive
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
 
-      - name: Prepare
-        run: bash src/libCacheSim/scripts/install_dependency.sh
+      - name: Install system dependencies (Ubuntu)
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y pkg-config libglib2.0-dev libzstd-dev
 
-      - name: Build main libCacheSim project
+      - name: Install system dependencies (macOS)
+        if: matrix.os == 'macos-latest' || matrix.os == 'macos-14'
         run: |
-          pushd src/libCacheSim
-          cmake -G Ninja -B build
-          ninja -C build
-          popd
+          brew install glib pkg-config zstd argp-standalone
 
-      - name: Build libCacheSim-python
+      - name: Build and test with uv
         run: |
-          pip install -e .[dev]
+          uv venv --python ${{ matrix.python-version }}
+          uv pip install -e .[dev]
+          uv run python -c "import libcachesim; print('✓ Import successful for Python ${{ matrix.python-version }} on ${{ matrix.os }}')"
 
       - name: Run tests
         run: |
-          python -m pytest tests/
+          if [ -d "tests" ]; then
+            uv run python -m pytest tests/ -v
+          else
+            echo "No tests directory found, skipping tests"
+          fi
 
   docs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
-      - name: Set up Python
-        uses: actions/setup-python@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
         with:
-          python-version: "3.x"
+          version: "latest"
 
-      - name: Cache dependencies
-        uses: actions/cache@v3
-        with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-docs-${{ hashFiles('docs/requirements.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-docs-
+      - name: Set up Python
+        run: uv python install 3.11
 
-      - name: Install documentation dependencies
+      - name: Install documentation dependencies and build
         run: |
+          # Install MkDocs and dependencies using pip in a temporary venv
+          python3 -m venv temp-docs-env
+          source temp-docs-env/bin/activate
           pip install -r docs/requirements.txt
-
-      - name: Test documentation build
-        run: |
           cd docs
           mkdocs build --clean --strict

CMakeLists.txt

@@ -3,6 +3,50 @@ project(libCacheSim-python)
 set(DESCRIPTION "The libCacheSim Python Package")
 set(PROJECT_WEB "http://cachemon.github.io/libCacheSim-python")
 
+# Auto-initialize submodules if not already done
+find_package(Git QUIET)
+if(GIT_FOUND AND EXISTS "${PROJECT_SOURCE_DIR}/.git")
+    # Check if submodule is initialized
+    if(NOT EXISTS "${PROJECT_SOURCE_DIR}/src/libCacheSim/CMakeLists.txt")
+        message(STATUS "Initializing git submodules...")
+        execute_process(COMMAND ${GIT_EXECUTABLE} submodule update --init --recursive
+                        WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
+                        RESULT_VARIABLE GIT_SUBMOD_RESULT)
+        if(NOT GIT_SUBMOD_RESULT EQUAL "0")
+            message(FATAL_ERROR "git submodule update --init --recursive failed with ${GIT_SUBMOD_RESULT}")
+        endif()
+    endif()
+endif()
+
+# Auto-build libCacheSim if needed
+set(LIBCACHESIM_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/src/libCacheSim")
+if(NOT EXISTS "${LIBCACHESIM_SOURCE_DIR}/CMakeLists.txt")
+    message(FATAL_ERROR "libCacheSim submodule not found. Please run 'git submodule update --init --recursive'")
+endif()
+
+# Build libCacheSim first
+set(LIBCACHESIM_BUILD_DIR "${CMAKE_CURRENT_SOURCE_DIR}/src/libCacheSim/build")
+if(NOT EXISTS "${LIBCACHESIM_BUILD_DIR}/export_vars.cmake")
+    message(STATUS "Building libCacheSim...")
+    execute_process(
+        COMMAND ${CMAKE_COMMAND} -S ${LIBCACHESIM_SOURCE_DIR} -B ${LIBCACHESIM_BUILD_DIR} -G Ninja
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+        RESULT_VARIABLE CMAKE_CONFIG_RESULT
+    )
+    if(NOT CMAKE_CONFIG_RESULT EQUAL "0")
+        message(FATAL_ERROR "Failed to configure libCacheSim")
+    endif()
+
+    execute_process(
+        COMMAND ${CMAKE_COMMAND} --build ${LIBCACHESIM_BUILD_DIR}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+        RESULT_VARIABLE CMAKE_BUILD_RESULT
+    )
+    if(NOT CMAKE_BUILD_RESULT EQUAL "0")
+        message(FATAL_ERROR "Failed to build libCacheSim")
+    endif()
+endif()
+
 # Note(haocheng): now we still utilize the exported cache from 
 # the main project, which should be deprecated soon 
 
@@ -49,6 +93,9 @@ else()
     add_compile_definitions(LOGLEVEL=7)
 endif()
 
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
 # Find python and pybind11
 find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
 find_package(pybind11 CONFIG REQUIRED)

docs/mkdocs.yml

@@ -1,53 +1,62 @@
-site_name: libCacheSim Python Documentation
+site_name: libCacheSim Python
 site_url: https://cachemon.github.io/libCacheSim-python/
 repo_url: https://github.com/cacheMon/libCacheSim-python
 repo_name: cacheMon/libCacheSim-python
+edit_uri: edit/main/docs/src/
 
 docs_dir: src
 
 nav:
-  - Home: index.md
-  - Quick Start: quickstart.md
-  - API Reference: api.md
-  - Examples: examples.md
+  - Home: 
+    - libCacheSim Python: index.md
+  - Getting Started:
+    - Quick Start: quickstart.md
+  - API Reference:
+    - API Documentation: api.md
+  - Examples:
+    - Usage Examples: examples.md
 
 theme:
   name: material
   language: en
   palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
     # Palette toggle for light mode
-    - scheme: default
-      primary: custom
-      accent: custom
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: white
       toggle:
         icon: material/brightness-7
         name: Switch to dark mode
-    # Palette toggle for dark mode  
-    - scheme: slate
-      primary: custom
-      accent: custom
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
       toggle:
         icon: material/brightness-4
-        name: Switch to light mode
+        name: Switch to system preference
   font:
     text: Open Sans
   features:
-    - header.autohide
+    - content.action.edit
+    - content.code.copy
+    - content.tabs.link
+    - navigation.tracking
     - navigation.tabs
-    - navigation.footer
+    - navigation.tabs.sticky
     - navigation.sections
-    - navigation.expand
-    - navigation.path
+    - navigation.prune
     - navigation.top
-    - toc.follow
     - search.highlight
     - search.share
-    - search.suggest
-    - content.code.copy
-    - content.code.annotate
+    - toc.follow
 
 extra_css:
-  - ../stylesheets/extra.css
+  - stylesheets/extra.css
 
 plugins:
   - search
@@ -71,25 +80,29 @@ plugins:
             Examples: 使用示例
 
 markdown_extensions:
+  - attr_list
+  - md_in_html
   - admonition
   - pymdownx.details
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid
           class: mermaid
           format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
   - pymdownx.highlight:
       anchor_linenums: true
       line_spans: __span
       pygments_lang_class: true
   - pymdownx.inlinehilite
   - pymdownx.snippets
-  - pymdownx.tabbed:
-      alternate_style: true
   - pymdownx.keys
   - pymdownx.mark
   - pymdownx.tilde
-  - codehilite
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - toc:
       permalink: true
   - tables

docs/src/en/plugin.md

@@ -0,0 +1,16 @@
+# Plugin System
+
+We enable user add any customized cache via libCacheSim's plugin system.
+
+With user-defined sive python hook functions, 
+
+```c++
+  py::function cache_init_hook;
+  py::function cache_hit_hook;
+  py::function cache_miss_hook;
+  py::function cache_eviction_hook;
+  py::function cache_remove_hook;
+  py::function cache_free_hook;
+```
+
+We can simulate and determine the cache eviction behavior from the python side.