Merge pull request #15 from Smithsonian/apidocs

README update and apidocs build via GitHub Actions

.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: API Documentation
+on: 
+  push:
+    branches:
+      - main
+    paths:
+      - 'src/**'
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+
+  pull_request:
+    paths:
+      - 'src/**'
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+
+jobs:
+
+  apidocs:
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: Check out smax-python
+      uses: actions/checkout@v4
+
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+
+    - name: Install Sphinx and RTM theme
+      run: pip install sphinx sphinx-rtd-theme
+
+    - name: Build docs
+      run: |
+        cd docs
+        sphinx-apidoc -o . ../src/smax
+        sphinx-build -M html . .
+          
+    - name: Checkout gh-pages
+      uses: actions/checkout@v4
+      with:
+        ref: 'gh-pages'
+        path: site
+
+    - name: copy docs to gh-pages
+      run: cp -a docs/html/* 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

.github/workflows/python_tests.yml

@@ -4,8 +4,14 @@ on:
   push:
     branches:
       - main
+    paths:
+      - 'src/**'
+      - '.github/workflows/python_tests.yml'
 
   pull_request:
+    paths:
+      - 'src/**'
+      - '.github/workflows/python_tests.yml'
 
 jobs:
   build:

README.md

@@ -1,13 +1,54 @@
 [![pytest](https://github.com/Smithsonian/sma-python-redis-client/actions/workflows/python_tests.yml/badge.svg)](https://github.com/Smithsonian/sma-python-redis-client/actions/workflows/python_tests.yml)
 
+<picture>
+  <source srcset="resources/CfA-logo-dark.png" alt="CfA logo" media="(prefers-color-scheme: dark)"/>
+  <source srcset="resources/CfA-logo.png" alt="CfA logo" media="(prefers-color-scheme: light)"/>
+  <img src="resources/CfA-logo.png" alt="CfA logo" width="400" height="67" align="right"/>
+</picture>
+<br clear="all">
+
 # SMAX for Python 
-Client side python library for communicating with SMA-X (aka Redis).
+
+Client side python library for the [SMA Exchange (SMA-X)](https://docs.google.com/document/d/1eYbWDClKkV7JnJxv4MxuNBNV47dFXuUWu7C4Ve_YTf0/edit?usp=sharing) realtime structured database.
 
 Version 1.0.3
 
-[API Documentation](https://ideal-funicular-124903cd.pages.github.io/)
+- [API Documentation](https://smithsonian.github.io/smax-python/)
+
+
+## Table of Contents
+
+ - [Introduction](#introduction)
+ - [Installing](#installing)
+ - [Examples](#examples)
+
+<a name="introduction"></a>
+## Introduction
+
+The [SMA Exchange (SMA-X)](https://docs.google.com/document/d/1eYbWDClKkV7JnJxv4MxuNBNV47dFXuUWu7C4Ve_YTf0/edit?usp=sharing) 
+is a high performance and versatile real-time data sharing platform for distributed software systems. It is built 
+around a central Redis database, and provides atomic access to structured data, including specific branches and/or 
+leaf nodes, with associated metadata. SMA-X was developed at the Submillimeter Array (SMA) observatory, where we use 
+it to share real-time data among hundreds of computers and nearly a thousand individual programs.
+
+SMA-X consists of a set of server-side [LUA](https://lua.org/) scripts that run on [Redis](https://redis.io) (or one 
+of its forks / clones such as [Valkey](https://valkey.io) or [Dragonfly](https://dragonfly.io)); a set of libraries to 
+interface client applications; and a set of command-line tools built with them. Currently we provide client libraries 
+for Python 3 and C/C++ (C99). This repository contains the Python 3 client libraries for SMA-X.
+
+There are no official releases of __smax-python__ yet. An initial 1.0.0 release is expected early/mid 2025. 
+Before then the API may undergo slight changes and tweaks. Use the repository as is at your own risk for now.
 
-# Install
+### Related links
+
+ - [SMA-X specification](https://docs.google.com/document/d/1eYbWDClKkV7JnJxv4MxuNBNV47dFXuUWu7C4Ve_YTf0/edit?usp=sharing)
+ - [Smithsonian/smax-clib](https://github.com/Smithsonian/smax-clib) an alternative library for C/C++ (C99).
+ - [Smithsonian/smax-postgres](https://github.com/Smithsonian/smax-postgres) for creating a time-series history of 
+   SMA-X in a __PostgreSQL__ database.
+
+
+<a name="introduction"></a>
+## Installing
 There is a proper python package in this repo named "smax".  You can use pip to install
 directly from the repo, which is useful if you just need to import the library for your
 own application. For development of this package, clone the repo and install with the 
@@ -37,42 +78,46 @@ pip install . -e
 * Set up the SMA-X server on top of Redis
   1. Clone [Smithsonian/smax-server](https://github.com/Smithsonian/smax-server)
   2. In `smax-server`: edit `redis.conf` files as necessary or desired for your application.
-  3. In `smax-server`: run `install.sh`.
-* Clone this repo locally
-* That's it, you now have SMAX running locally!
+  3. In `smax-server`: run `sudo install.sh`.
+* Clone this repo ([Smithsonian/smax-python](https://github.com/Smithsonian/smax-python)) locally
+
+That's it, you now have SMAX running locally.
 
 
-# Python Examples
-The best place to find example usages is the unit tests (test_smax_redis_client.py), but here are 
+<a name="examples"></a>
+## Examples
+
+The best place to find example usages is the unit tests (`test_smax_redis_client.py`), but here are 
 a few simple ones to help get you started.
 
 ### Share/Pull roundtrip
 ```python
-from smax import SmaxRedisClient
-
-smax_client = SmaxRedisClient("localhost") # Replace localhost with redis hostname or IP.
-value = 0.183
-table = "weather:forecast:gfs"
-key = "test_tau"
-smax_client.smax_share(table, key, value)
-result = smax_client.smax_pull(table, key)
-print(result.data, result.type)
+  from smax import SmaxRedisClient
+
+  smax_client = SmaxRedisClient("localhost") # Replace localhost with redis hostname or IP.
+  value = 0.183
+  table = "weather:forecast:gfs"
+  key = "test_tau"
+  smax_client.smax_share(table, key, value)
+  result = smax_client.smax_pull(table, key)
+  print(result.data, result.type)
 ```
-### Pubsub
+### Pub/sub
+
 ```python
-from smax import SmaxRedisClient
+  from smax import SmaxRedisClient
 
-smax_client = SmaxRedisClient("localhost") # Replace localhost with redis hostname or IP.
-table = "weather:forecast:gfs"
-key = "test_array"
-smax_client.smax_subscribe(f"{table}:{key}")
+  smax_client = SmaxRedisClient("localhost") # Replace localhost with redis hostname or IP.
+  table = "weather:forecast:gfs"
+  key = "test_array"
+  smax_client.smax_subscribe(f"{table}:{key}")
 
-# Share something, which send publish notifications automatically.
-value = [0.0, 1.12345, -1.54321, 100000.12345]
-smax_client.smax_share(table, key, value)
+  # Share something, which send publish notifications automatically.
+  value = [0.0, 1.12345, -1.54321, 100000.12345]
+  smax_client.smax_share(table, key, value)
 
-# Wait for publish notifications.
-result = smax_client.smax_wait_on_any_subscribed()
-print(result.data, result.type)
+  # Wait for publish notifications.
+  result = smax_client.smax_wait_on_any_subscribed()
+  print(result.data, result.type)
 ```
 

docs/conf.py

@@ -0,0 +1,32 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import sys
+import os
+sys.path.insert(0, os.path.abspath('../src/'))
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'smax'
+copyright = '2024, Center for Astrohysics | Harvard & Smithsonian' 
+author = 'Paul Grimes, Christopher Moriarty, Robert Wilson'
+release = '1.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.napoleon' ]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']