Publish Docs

.github/workflows/docs.yml

@@ -0,0 +1,92 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+env:
+  PYTHON_VERSION: '3.12'
+  _SMARTREDIS_VERSION: "develop"
+  _DRAGON_VERSION: "main"
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-docs-${{ hashFiles('dev-resources/requirements-doc.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-docs-
+            ${{ runner.os }}-pip-
+
+      - name: Linux dependencies
+        run: |
+              sudo apt-get update
+              sudo apt-get install -y build-essential gcc g++ make cmake mpich libnuma-dev doxygen
+
+      - name: Install DragonHPC
+        run: |
+              git clone https://github.com/DragonHPC/dragon.git
+              pushd dragon && git checkout $_DRAGON_VERSION && pushd devtools && source VARIABLES && popd && pip install -e src/
+
+      - name: Install Redis backend
+        run: |
+              git clone -b $_SMARTREDIS_VERSION --single-branch https://github.com/CrayLabs/SmartRedis.git
+              cd SmartRedis && make lib
+
+      - name: Set Radex SmartRedis Environment Variables
+        run: |
+              SR_LIB_DIR=$(find ${PWD}/SmartRedis/install -maxdepth 1 -name 'lib*' -type d)
+              echo "smartredis_DIR=SmartRedis/install/share/cmake/smartredis" >> $GITHUB_ENV
+              echo "SMARTREDIS_INCLUDE_DIR=${PWD}/SmartRedis/install/include" >> $GITHUB_ENV
+              echo "SMARTREDIS_LIB_DIR=${SR_LIB_DIR}" >> $GITHUB_ENV
+              echo "LD_LIBRARY_PATH=${SR_LIB_DIR}:${LD_LIBRARY_PATH}" >> $GITHUB_ENV
+
+      - name: Build radex library
+        run: |
+              cmake -S . -B build \
+                -DCMAKE_INSTALL_PREFIX=install \
+                -DALLOW_SYSTEM_PYTHON=ON \
+                -DPython3_FIND_STRATEGY=LOCATION \
+                -DPython3_ROOT_DIR="${pythonLocation}"
+              cmake --build build -j
+              cmake --install build
+
+      - name: Install doc dependencies
+        run: |
+              pip install -r dev-resources/requirements-doc.txt
+
+      - name: Build docs
+        run: make -f dev-resources/Makefile docs
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -29,6 +29,7 @@ install/
 
 # Docs
 site/
-docs/api/
+docs/api/*
+!docs/api/index.md
 docs/radexCpp/
 docs/doxyoutput/

docs/api/index.md

@@ -0,0 +1,11 @@
+# API Reference
+
+radex ships a C++ core with two language bindings: a Cython-based Python client and a native C++ client.
+
+## Python
+
+The **Python** section in the nav is generated automatically from the docstrings in the `radex` package (`src/python/src/radex`). It's built when `radex` is importable in the environment running `mkdocs build` — see [Installation](../getting-started/installation.md) for how to build and install it.
+
+## C++
+
+The **C++** section is generated from the headers under `include/radex` via [Doxygen](https://www.doxygen.nl/) and [mkdoxy](https://mkdoxy.kubaandrysek.cz/), starting at [radexCpp/annotated.md](../radexCpp/annotated.md).

docs/gen_ref_pages.py

@@ -51,5 +51,5 @@
 
         mkdocs_gen_files.set_edit_path(full_doc_path, path)
 
-    with mkdocs_gen_files.open("api/SUMMARY.md", "w") as nav_file:
-        nav_file.writelines(nav.build_literate_nav())
+with mkdocs_gen_files.open("api/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

docs/stylesheets/extra.css

@@ -1,15 +1,27 @@
 /* RaDex Documentation Extra Styles */
 
 :root {
-  --radex-primary: #455a64;
-  /* Blue Grey 700 */
-  --radex-secondary: #00897b;
-  /* Teal 600 */
-  --md-primary-fg-color: var(--radex-primary);
-  --md-accent-fg-color: var(--radex-secondary);
+  --radex-sage: #9f9a7f;
+  /* primary: requested #9F9A7F */
+  --radex-sage-text: #2b2a22;
+  /* dark text for legibility on the sage header/tabs bar */
+  --radex-almond: #efdecd;
+  /* accent: requested "almondine" */
+  --radex-almond-dark: #8b6644;
+  /* almond, darkened to stay legible as link/accent text on a light page */
+
+  --md-primary-fg-color: var(--radex-sage);
+  --md-primary-bg-color: var(--radex-sage-text);
+  --md-accent-fg-color: var(--radex-almond-dark);
+}
+
+/* On the dark (slate) scheme the page background is dark, so the pale
+   almondine itself reads clearly as the accent color without darkening. */
+[data-md-color-scheme="slate"] {
+  --md-accent-fg-color: var(--radex-almond);
 }
 
 .md-nav__item--active > .md-nav__link {
-  color: var(--radex-secondary) !important;
+  color: var(--md-accent-fg-color) !important;
   font-weight: 700;
 }

mkdocs.yml

@@ -36,15 +36,15 @@ theme:
         name: Switch to light mode
     # Palette toggle for light mode
     - media: "(prefers-color-scheme: light)"
-      primary: blue grey
-      accent: teal
+      primary: custom
+      accent: custom
       toggle:
         icon: material/brightness-7
         name: Switch to dark mode
     # Palette toggle for dark mode
     - media: "(prefers-color-scheme: dark)"
-      primary: blue grey
-      accent: teal
+      primary: custom
+      accent: custom
       scheme: slate
       toggle:
         icon: material/brightness-4