dox.yml: fixes

Smithsonian · Sep 3, 2024 · 134d152 · 134d152
1 parent 2a7f1c0
commit 134d152
Show file tree

Hide file tree

Showing 2 changed files with 86 additions and 52 deletions.
diff --git a/.github/workflows/dox.yml b/.github/workflows/dox.yml
@@ -12,8 +12,8 @@ on:
       - 'Doxyfile'
       - '*.md'
       - '.github/workflows/dox.yml'
-      
-jobs:   
+
+jobs:
 
   apidocs:
     name: Generate API documentation
@@ -26,103 +26,105 @@ jobs:
 
     - name: install doxygen
       run: sudo apt-get install doxygen
-   
+
     - name: Check out RedisX
       uses: actions/checkout@v4
-      with: 
-      	path: redisx
-
-    - name: Check out xchange 
-      uses: actions/checkout@v4
-      with:
-        repository: Smithsonian/xchange
-        path: xchange
-
-    - name: Generate xchange docs
-      run: make -C xchange dox
-
+
     - name: Generate docs
-      run: make -C redisx dox
- 
+      run: make local-dox
+
   site-update:
     name: Update github pages
-    working-directory: ./redisx
     needs: apidocs
     if: github.repository_owner == 'Smithsonian' && (github.event_name == 'release' || contains(github.event.head_commit.message, 'site update'))
- 
+
     runs-on: ubuntu-latest
     steps:
-    
+
     - name: Checkout source
       uses: actions/checkout@v4
-
+      with:
+        repository: Smithsonian/redisx
+        path: redisx
+
+    - name: Check out xchange
+      uses: actions/checkout@v4
+      with:
+        repository: Smithsonian/xchange
+        path: xchange
+
     - name: Generate headless README
-      run: make README-orig.md
-
-    - uses: mattnotmitt/[email protected]
+      run: make -C redisx README-orig.md
+
+    - name: Generate xchange apidocs
+      uses: mattnotmitt/[email protected]
       with:
         additional-packages: font-roboto
-
+        working-directory: ./xchange
+
+    - name: Generate RedisX apidocs
+      uses: mattnotmitt/[email protected]
+      with:
+        additional-packages: font-roboto
+        working-directory: ./redisx
+
     - name: Checkout gh-pages
       uses: actions/checkout@v4
       with:
         ref: 'gh-pages'
         path: site
 
     - name: Assert site/doc/
-      run: mkdir -p site/doc 
+      run: mkdir -p site/doc
 
     - name: Copy README
       run: |
-        echo '<img src="/xchange/resources/CfA-logo.png" alt="CfA logo" width="400" height="67" align="right">' > site/doc/README.md
+        echo '<img src="/redisx/resources/CfA-logo.png" alt="CfA logo" width="400" height="67" align="right">' > site/doc/README.md
         echo '<br clear="all">' >> site/doc/README.md
-        cat README-orig.md >> site/doc/README.md
-        
+        cat redisx/README-orig.md >> site/doc/README.md
+
     - name: Copy CHANGELOG
-      run: cp CHANGELOG.md site/doc/
-      
+      run: cp redisx/CHANGELOG.md site/doc/
+
     - name: Copy API documentation
-      run: cp -a apidoc site/
-        
+      run: cp -a redisx/apidoc site/
+
     - name: Push to pages
       run: |
         cd site
         git config --global user.email "$GITHUB_JOB+github-actions[bot]@users.noreply.github.com"
         git config --global user.name "github-actions"
         git add -A
         git commit -m "[automated site update]" && git push || true
-        
-        
+
+
   changelog-update:
     name: Update CHANGELOG on github pages
-    working-directory: ./redisx
     if: github.repository_owner == 'Smithsonian' && contains(github.event.head_commit.message, 'changelog update')
-   
+
     runs-on: ubuntu-latest
     steps:
-    
+
     - name: Checkout source
       uses: actions/checkout@v4
-       
+
     - name: Checkout gh-pages
       uses: actions/checkout@v4
       with:
         ref: 'gh-pages'
         path: site
 
     - name: Assert site/doc/
-      run: mkdir -p site/doc 
-        
+      run: mkdir -p site/doc
+
     - name: Copy CHANGELOG
       run: cp CHANGELOG.md site/doc/
-        
+
     - name: Push to pages
       run: |
         cd site
         git config --global user.email "$GITHUB_JOB+github-actions[bot]@users.noreply.github.com"
         git config --global user.name "github-actions"
         git add -A
         git commit -m "[automated site update]" && git push || true
-    
-
-
+
diff --git a/README.md b/README.md
@@ -1,5 +1,11 @@
-![Build Status](https://github.com/Smithsonian/SuperNOVAS/actions/workflows/build.yml/badge.svg)
-![Static Analysis](https://github.com/Smithsonian/SuperNOVAS/actions/workflows/check.yml/badge.svg)
+![Build Status](https://github.com/Smithsonian/redisx/actions/workflows/build.yml/badge.svg)
+![Static Analysis](https://github.com/Smithsonian/redisx/actions/workflows/check.yml/badge.svg)
+<a href="https://smithsonian.github.io/redisx/apidoc/html/files.html">
+ ![API documentation](https://github.com/Smithsonian/redisx/actions/workflows/dox.yml/badge.svg)
+</a>
+<a href="https://smithsonian.github.io/redisx/index.html">
+ ![Project page](https://github.com/Smithsonian/redisx/actions/workflows/pages/pages-build-deployment/badge.svg)
+</a>
 
 <picture>
   <source srcset="resources/CfA-logo-dark.png" alt="CfA logo" media="(prefers-color-scheme: dark)"/>
@@ -16,9 +22,9 @@ A simple, light-weight C/C++ Redis client.
 ## Table of Contents
 
  - [Introduction](#introduction)
- - [Pre-requisites](#pre-requisites)
- - [Buildding RedisX](#building-redisx)
- - [Managing Redis server connetions](#managing-redis-server-connections)
+ - [Prerequisites](#prerequisites)
+ - [Building RedisX](#building-redisx)
+ - [Managing Redis server connections](#managing-redis-server-connections)
  - [Simple Redis queries](#simple-redis-queries)
  - [Atomic execution blocks and LUA scripts](#atomic-transaction-blocks-and-lua-scripts)
  - [Publish/subscribe (PUB/SUB) support](#publish-subscribe-support)
@@ -58,8 +64,8 @@ There are no official releases of __RedisX__ yet. An initial 1.0.0 release is ex
 
 -----------------------------------------------------------------------------
 
-<a name="pre-requisites"></a>
-## Pre-requisites
+<a name="prerequisites"></a>
+## Prerequisites
 
 The [Smithsonian/xchange](https://github.com/Smithsonian/xchange) library is both a build and a runtime dependency of 
 RedisX.
@@ -360,6 +366,7 @@ with the approrpiate mutex locked to prevent concurrency issues.
   // other requests concurrently...
   redisxLockEnabled(pipe);
 
+  // -------------------------------------------------------------------------
   // Submit a whole bunch of asynchronous requests, e.g. from a loop...
   for (...) {
     int status = redisxSendRequestAsync(pipe, ...);
@@ -374,6 +381,7 @@ with the approrpiate mutex locked to prevent concurrency issues.
       ...
     }
   }
+  // -------------------------------------------------------------------------
   
   // Release the exclusive lock on the pipeline channel, so
   // other threads may use it now that we sent off our requests...
@@ -693,11 +701,35 @@ subscriber function as appropriate (provided no other subscription needs it) via
 <a name="error-handling"></a>
 ## Error handling
 
+Error handling of RedisX is an extension of that of __xchange__, with further error codes defined in `redisx.h`. 
+The RedisX functions that return an error status (either directly, or into the integer designated by a pointer 
+argument), can be inspected by `redisxErrorDescription()`, e.g.:
+
+```c
+  Redis *redis ...
+  int status = redisxSetValue(...);
+  if (status != X_SUCCESS) {
+    // Ooops, something went wrong...
+    fprintf(stderr, "WARNING! set value: %s", redisErrorDescription(status));
+    ...
+  }
+```
+
+
 -----------------------------------------------------------------------------
 
 <a name="debug-support"></a>
 ## Debug support
 
+The __xchange__ library provides two macros: `xvprintf()` and `xdprintf()`, for printing verbose and debug messages
+to `stderr`. Both work just like `printf()`, but they are conditional on verbosity being enabled via 
+`xSetVerbose(boolean)` and the global variable `xDebug` being `TRUE` (non-zero), respectively. Applications using 
+__xchange__ may use these macros to produce their own verbose and/or debugging outputs conditional on the same global 
+settings. 
+
+You can also turn debug messages by defining the `DEBUG` constant for the compiler, e.g. by adding `-DDEBUG` to 
+`CFLAGS` prior to calling `make`. 
+
 -----------------------------------------------------------------------------
 
 <a name="future-plans"></a>