From 4d2e370369071e827e9a4d99b389cad871363dfc Mon Sep 17 00:00:00 2001 From: tbedford Date: Fri, 17 Mar 2023 11:31:18 +0000 Subject: [PATCH 1/2] [chore] - rename sdk to client library --- .github/workflows/build-commit-subfolder.yaml | 32 ++++++++--------- .github/workflows/sync-build-deploy.yaml | 34 +++++++++---------- GUIDE.md | 24 ++++++------- docs/apis/index.md | 4 +-- docs/apis/streaming-reader-api/intro.md | 2 +- docs/apis/streaming-writer-api/intro.md | 2 +- docs/index.md | 20 +++++------ docs/platform/definitions.md | 9 +++-- docs/platform/how-to/use-sdk-token.md | 2 +- docs/platform/intro.md | 18 +++++----- .../troubleshooting/troubleshooting.md | 11 +++--- .../eventDetection/data-acquisition.md | 2 +- .../tutorials/image-processing/decode.md | 2 +- .../train-and-deploy-ml/deploy-ml.md | 2 +- docs/sdk-intro.md | 2 +- mkdocs.yml | 2 +- 16 files changed, 83 insertions(+), 85 deletions(-) diff --git a/.github/workflows/build-commit-subfolder.yaml b/.github/workflows/build-commit-subfolder.yaml index 1e8ef02e..c47f8567 100644 --- a/.github/workflows/build-commit-subfolder.yaml +++ b/.github/workflows/build-commit-subfolder.yaml @@ -69,46 +69,46 @@ jobs: - run: pip install mkdocs #- run: pip install mkdocs-material - # enable when there is an SDK dev branch + # enable when there is an Client Library dev branch # - name: Extract branch name # shell: bash # run: echo "##[set-output name=branch;]$(echo ${GITHUB_REF#refs/heads/})" # id: extract_branch - # checkout sdk files - - name: Checkout SDK + # checkout client library files + - name: Checkout Client Library uses: actions/checkout@v3 with: repository: 'quixio/quix-streams' ref: 'main' # when a dev branch exists we can get the dev content #ref: '{{ steps.extract_branch.outputs.branch }}' - path: 'sdk' + path: 'client-library' - # copy sdk readme to sdk intro.md - - name: Copy and rename sdk's intro.md + # copy client-library readme to client-library intro.md + - name: Copy and rename client library intro.md shell: bash - run: cp sdk/README.md docs/sdk-intro.md + run: cp client-library/README.md docs/client-library-intro.md - # copy sdk images to sdk intro.md - - name: Copy SDK Quix image + # copy client library images to client library intro.md + - name: Copy Client Library Quix image shell: bash - run: cp sdk/images/quixstreams-banner.jpg docs/assets/quixstreams-banner.jpg + run: cp client-library/images/quixstreams-banner.jpg docs/assets/quixstreams-banner.jpg - # copy sdk images to docs/assets/sdk/ - - name: Copy SDK waveform image + # copy client library images to docs/assets/client-library/ + - name: Copy client library waveform image shell: bash - run: cp -r sdk/images/. docs/assets/sdk/ + run: cp -r client-library/images/. docs/assets/client-library/ # Change image URL in the copied file to new location # sed -i 's/old-text/new-text/g' input.txt - name: Update intro.md shell: bash - run: "sed -i 's,https://github.com/quixio/.github/blob/main/profile,./assets,g' docs/sdk-intro.md" + run: "sed -i 's,https://github.com/quixio/.github/blob/main/profile,./assets,g' docs/client-library-intro.md" - # Change image paths from ./images to ./assets/sdk + # Change image paths from ./images to ./assets/client-library - name: Update intro.md shell: bash - run: "sed -i 's,./images,./assets/sdk/,g' docs/sdk-intro.md" + run: "sed -i 's,./images,./assets/client-library/,g' docs/client-library-intro.md" # clone the library repo - name: Checkout Library diff --git a/.github/workflows/sync-build-deploy.yaml b/.github/workflows/sync-build-deploy.yaml index 1c61a457..439150fd 100644 --- a/.github/workflows/sync-build-deploy.yaml +++ b/.github/workflows/sync-build-deploy.yaml @@ -77,48 +77,48 @@ jobs: uses: actions/configure-pages@v2 #################################################### - ### COPY AND MASSAGE SDK DOCS REPO README INTO DOCS + ### COPY AND MASSAGE Client Library DOCS REPO README INTO DOCS #################################################### - # enable when there is an SDK dev branch + # enable when there is an client library dev branch # - name: Extract branch name # shell: bash # run: echo "##[set-output name=branch;]$(echo ${GITHUB_REF#refs/heads/})" # id: extract_branch - # checkout sdk files - - name: Checkout SDK + # checkout client library files + - name: Checkout Client Library uses: actions/checkout@v3 with: repository: 'quixio/quix-streams' ref: 'main' # when a dev branch exists we can get the dev content #ref: '{{ steps.extract_branch.outputs.branch }}' - path: 'sdk' + path: 'client-library' - # copy sdk readme to sdk intro.md - - name: Copy and rename sdk's intro.md + # copy client library readme to client library intro.md + - name: Copy and rename client library intro.md shell: bash - run: cp sdk/README.md docs/sdk-intro.md + run: cp client-library/README.md docs/client-library-intro.md - # copy sdk images to sdk intro.md - - name: Copy SDK Quix image + # copy client library images to client library intro.md + - name: Copy Client Library Quix image shell: bash - run: cp sdk/images/quixstreams-banner.jpg docs/assets/quixstreams-banner.jpg + run: cp client-library/images/quixstreams-banner.jpg docs/assets/quixstreams-banner.jpg - # copy sdk images to docs/assets/sdk/ - - name: Copy SDK waveform image + # copy client library images to docs/assets/client-library/ + - name: Copy Client Library waveform image shell: bash - run: cp -r sdk/images/. docs/assets/sdk/ + run: cp -r client-library/images/. docs/assets/client-library/ # Change image URL in the copied file to new location # sed -i 's/old-text/new-text/g' input.txt - name: Update intro.md shell: bash - run: "sed -i 's,https://github.com/quixio/.github/blob/main/profile,./assets,g' docs/sdk-intro.md" + run: "sed -i 's,https://github.com/quixio/.github/blob/main/profile,./assets,g' docs/client-library-intro.md" - # Change image paths from ./images to ./assets/sdk + # Change image paths from ./images to ./assets/client-library - name: Update intro.md shell: bash - run: "sed -i 's,./images,./assets/sdk/,g' docs/sdk-intro.md" + run: "sed -i 's,./images,./assets/client-library/,g' docs/client-library-intro.md" #################################################### ### END diff --git a/GUIDE.md b/GUIDE.md index 88b17c83..34c43494 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -37,10 +37,10 @@ Use the following guidelines regarding the company's name: * Managed Kafka * Serverless compute * Data catalogue - * SDK and APIs - * Quix Streams is our SDK: - * An SDK is a collection of code specific to one programming language. Data scientists refer to SDKs as client libraries. - * Quix currently offers Python and C# SDKs. + * APIs + * Quix Streams is our client library: + * A client library is a collection of code specific to one programming language. + * Quix currently offers Python and C# client libraries. ### Industry and Quix terms @@ -157,8 +157,8 @@ Examples: * *Passive voice:* The apple was eaten by the man. * *Active voice:* The client creates the connection. * *Passive voice:* The connection is created by the client. -* *Active voice:* Quix provides a Python SDK. -* *Passive voice:* A Python SDK is provided by Quix. +* *Active voice:* Quix provides a Python client library. +* *Passive voice:* A Python client library is provided by Quix. Active voice is simpler, more direct, and easier to translate. @@ -180,17 +180,17 @@ You can break out the bracketed text into a new sentence or rewrite the text to *Avoid:* - You can implement this in JavaScript (or Python using the Python SDK (otherwise know as the library)), or C# (with the .NET runtime). + You can implement this in JavaScript (or Python using the Python client library (otherwise known as the SDK)), or C# (with the .NET runtime). *Better:* You can implement your widget with: * JavaScript - * Python using the Python SDK + * Python using the Python client library * C# .NET - **Note:** SDKs are sometimes referred to as libraries. + **Note:** Libraries are sometimes referred to as SDKs. The general rule is avoid parentheses. @@ -231,8 +231,8 @@ Use Quix, rather than 'we', when referring to the company. Example: -* *Avoid:* We also provide a Python SDK. -* *Better:* Quix also provides a Python SDK. +* *Avoid:* We also provide a Python client library. +* *Better:* Quix also provides a Python client library. ## Avoid Latin phrases and abbreviations @@ -346,7 +346,7 @@ Some additional points to bear in mind: * Explain the *why* to the developer. Rather than simply state what a feature or function does, also explain why it is needed. * Avoid statements that predict the future, for example, "the next version will have feature X". There are good legal reasons for avoiding predicting the future. -* Avoid time-sensitive information. Specify an exact version where possible, for example '1.1', rather than 'current version' as the current version may change. Sometimes though you do want to use the terms 'current version' or 'latest version', for example: "The latest version of the Python SDK can always be downloaded from its GitHub repository". +* Avoid time-sensitive information. Specify an exact version where possible, for example '1.1', rather than 'current version' as the current version may change. Sometimes though you do want to use the terms 'current version' or 'latest version', for example: "The latest version of the Python client library can always be downloaded from its GitHub repository". * Avoid using ampersand ('&') instead of 'and', unless you are specifying a programming language operator or similar. * Avoid pricing information in *technical documentation* as it is subject to change, hard to maintain, and could lead to legal issues if wrong. Instead, direct developers to sales for the latest pricing information. diff --git a/docs/apis/index.md b/docs/apis/index.md index 1e40db21..7d76a1db 100644 --- a/docs/apis/index.md +++ b/docs/apis/index.md @@ -13,12 +13,12 @@ any language with HTTP capabilities. The [Streaming Writer API](streaming-writer-api/intro.md) allows you to stream data into the Quix platform via HTTP. It’s an alternative to -using our C\# and Python SDKs. You can use the Streaming Writer API from +using our C\# and Python client libraries. You can use the Streaming Writer API from any HTTP-capable language. ## Streaming Reader -As an alternative to the SDK, the Quix platform supports real-time data +As an alternative to the client library, the Quix platform supports real-time data streaming over WebSockets, via the [Streaming Reader API](streaming-reader-api/intro.md). Clients can receive updates on data and definitions for parameters and events, as they happen. The diff --git a/docs/apis/streaming-reader-api/intro.md b/docs/apis/streaming-reader-api/intro.md index 0558989f..036730d3 100644 --- a/docs/apis/streaming-reader-api/intro.md +++ b/docs/apis/streaming-reader-api/intro.md @@ -1,6 +1,6 @@ # Introduction -As an alternative to [the SDK](../../sdk/read.html), the Quix platform +As an alternative to [Quix Streams](../../client-library/read.html), the Quix platform supports real-time data streaming over WebSockets. Clients can receive updates on data and definitions for parameters and events, as they happen. The examples shown use the Microsoft diff --git a/docs/apis/streaming-writer-api/intro.md b/docs/apis/streaming-writer-api/intro.md index e1d12459..ebcf1906 100644 --- a/docs/apis/streaming-writer-api/intro.md +++ b/docs/apis/streaming-writer-api/intro.md @@ -2,7 +2,7 @@ The Streaming Writer API allows you to stream data into the Quix platform via HTTP endpoints or SignalR. It’s an alternative to using our -C\# and Python SDKs. You can use the Streaming Writer API from any +C\# and Python client libraries. You can use the Streaming Writer API from any HTTP-capable language. The API is fully documented in our [Swagger diff --git a/docs/index.md b/docs/index.md index fb6333a5..1683e74a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -69,33 +69,33 @@ By following these tutorials, you can learn how to build data-driven apps, and i ## Core resources -Read more about the Quix SDK and APIs. +Read more about the Quix Streams Client Library and APIs.
-- __Connect to Quix - SDK__ +- __Connect to Quix - Client Library__ --- - Discover how to connect Quix and your application using our SDK. + Discover how to connect Quix and your application using Quix Streams. - [:octicons-arrow-right-24: Learn more](./sdk/connect.md) + [:octicons-arrow-right-24: Learn more](./client-library/connect.md) -- __Publish data - SDK__ +- __Publish data - Client Library__ --- - Read how to publish real-time data to Kafka topics using the Quix SDK. + Read how to publish real-time data to Kafka topics using Quix Streams. - [:octicons-arrow-right-24: Learn more](./sdk/publish.html) + [:octicons-arrow-right-24: Learn more](./client-library/publish.html) -- __Subscribe to data - SDK__ +- __Subscribe to data - Client Library__ --- - Learn how to subscribe to real-time data in your application using the Quix SDK. + Learn how to subscribe to real-time data in your application using Quix Streams. - [:octicons-arrow-right-24: Learn more](./sdk/subscribe.html) + [:octicons-arrow-right-24: Learn more](./client-library/subscribe.html) - __Streaming Writer API__ diff --git a/docs/platform/definitions.md b/docs/platform/definitions.md index 6df130c5..e9f5057a 100644 --- a/docs/platform/definitions.md +++ b/docs/platform/definitions.md @@ -74,7 +74,7 @@ of numeric (double precision), string (UTF-8) and binary data (blobs). ### Parameters -Parameters are values that develop over time. The Quix SDK supports +Parameters are values that develop over time. Quix Streams supports numeric and string values. For example: @@ -173,10 +173,9 @@ Any application code that is run once. For example, use a job to run a batch import of data from an existing data store (CSV, DB or DataLake etc). -## SDK +## Quix Streams -[Quix SDK](../sdk/introduction.md) is the main library we use to send and -receive real-time data in our streaming applications. +[Quix Streams](../client-library/introduction.md) is the main client library we use to send and receive real-time data in our streaming applications. ## APIs @@ -185,7 +184,7 @@ receive real-time data in our streaming applications. A [HTTP API](../apis/streaming-writer-api/intro.md) used to send telemetry data from any source to a topic in the Quix platform. It should be used when it is not possible to use directly our -[SDK](../sdk/introduction.md). +[client library](../client-library/client-library-intro.md). ### Streaming Reader API diff --git a/docs/platform/how-to/use-sdk-token.md b/docs/platform/how-to/use-sdk-token.md index 1a1b430a..7e9eaaca 100644 --- a/docs/platform/how-to/use-sdk-token.md +++ b/docs/platform/how-to/use-sdk-token.md @@ -17,7 +17,7 @@ You can access these tokens by going to your topics and clicking on ## How to use These tokens can be used to authenticate against the API, but their -primary intended use is to be used with the [SDK QuixStreamingClient](../../sdk/connect.html#using-quixstreamingclient). +primary intended use is to be used with the [client library](../../client-library/connect.html). When using it with QuixStreamingClient, you no longer need to provide all broker credentials manually, they’ll be acquired when needed and set up automatically. diff --git a/docs/platform/intro.md b/docs/platform/intro.md index ae020f03..d86a6981 100644 --- a/docs/platform/intro.md +++ b/docs/platform/intro.md @@ -4,7 +4,7 @@ Quix is a platform for developing and deploying applications with streaming data. We architected Quix natively around a message broker (specifically -[Kafka](../sdk/kafka.md)) because we know databases are in the way of +[Kafka](../client-library/kafka.md)) because we know databases are in the way of building low-latency applications that scale cost-effectively. Instead of working with data on a disk, developers could work with live data in-memory, if broker technologies were easier to use. @@ -19,7 +19,7 @@ keeping your data in-memory, helping to achieve lower latencies and lower operating costs. From the top-down, our stack provides a Web UI, -[APIs](../apis/index.md) and [SDK](../sdk/introduction.md) that abstract +[APIs](../apis/index.md) and [Quix Streams](../client-library/introduction.md) that abstract developers off our underlying infrastructure, including fully-managed Kafka topics, serverless compute environment and a metadata-driven data catalogue (time-series database with steroids). @@ -70,7 +70,7 @@ include: [**Stream Writer API**](../apis/streaming-writer-api/intro.md): helps you send any data to a Kafka topic in Quix using HTTP. This API handles -encryption, serialization and conversion to the Quix SDK format ensuring +encryption, serialization and conversion to the Quix Streams format ensuring efficiency and performance of down-stream processing regardless of the data source. @@ -85,21 +85,21 @@ build dashboards and export data to other systems. [**Portal API**](../apis/portal-api.md): lets you automate Portal tasks like creating workspaces, topics and deployments. -## SDK +## Quix Streams Python is the dominant language for data science and machine learning, but it is quite incompatible with streaming technologies (like -[Kafka](../sdk/kafka.md)) which are predominantly written in Java and +[Kafka](../client-library/kafka.md)) which are predominantly written in Java and Scala. -Our [Quix streaming SDK](../sdk/introduction.md) is a client library that +Our [Quix Streams](../client-library/introduction.md) is a client library that abstracts Python developers off streaming-centric complexities like learning Java or dealing with buffering, serialization and encryption. -Instead, SDK serves you streaming data in a data frame so you can write +Instead, Quix Streams serves you streaming data in a data frame so you can write any simple or complex data processing logic and connect it directly to the broker. There are just a few key streaming concepts that you must -learn. You can read about them [here](../sdk/introduction.md). +learn. You can read about them [here](../client-library/introduction.md). ## Serverless compute @@ -191,7 +191,7 @@ your solution grows in data volume or complexity you can just add more topics without concern for the underlying infrastructure which is handled by us. -Together with our [SDK](../sdk/introduction.md) and serverless compute, you +Together with our [client library](../client-library/client-library-intro.md) and serverless compute, you can connect your models directly to our topics to read and write data using the pub/sub pattern. This keeps the data in-memory to deliver low-latency and cost effective stream processing capabilities. diff --git a/docs/platform/troubleshooting/troubleshooting.md b/docs/platform/troubleshooting/troubleshooting.md index 6e4ab203..0b4db080 100644 --- a/docs/platform/troubleshooting/troubleshooting.md +++ b/docs/platform/troubleshooting/troubleshooting.md @@ -74,9 +74,9 @@ The APIs that require a valid bearer token are: - -## Error Handling in the SDK callbacks +## Error Handling in the client library callbacks -Errors generated in the SDK callback can be swallowed or hard to read. +Errors generated in the client library callback can be swallowed or hard to read. To prevent this and make it easier to determine the root cause you should use a [traceback](https://docs.python.org/3/library/traceback.html){target=_blank} @@ -87,7 +87,7 @@ Begin by importing traceback import traceback ``` -Then, inside the SDK callback where you might have an issue place code +Then, inside the client library callback where you might have an issue place code similar to this: ``` python @@ -155,7 +155,7 @@ ModuleNotFoundError: No module named 'quixstreaming' ``` For information on how to setup your IDE for working with Quix please -check out this [section](../../sdk/python-setup.md) on the SDK +check out this [section](../../client-library/python-setup.md) in the client library documentation. ## Jupyter Notebooks @@ -164,8 +164,7 @@ If you are having trouble with Jupyter Notebooks or another consumer of Quix data try using aggregation to reduce the number of records returned. -For more info on aggregation check out this [short -video](https://youtu.be/fnEPnIunyxA). +For more info on aggregation check out this [short video](https://youtu.be/fnEPnIunyxA). ## Process Killed or Out of memory diff --git a/docs/platform/tutorials/eventDetection/data-acquisition.md b/docs/platform/tutorials/eventDetection/data-acquisition.md index 757dd004..d4149a5c 100644 --- a/docs/platform/tutorials/eventDetection/data-acquisition.md +++ b/docs/platform/tutorials/eventDetection/data-acquisition.md @@ -198,7 +198,7 @@ Follow these instructions to deploy the data source: - Opens the CSV file using Pandas. - - Renames some columns so the Quix SDK teams them as tags. + - Renames some columns so Quix Streams teams them as tags. - Then streams each row to the `phone-data` topic. diff --git a/docs/platform/tutorials/image-processing/decode.md b/docs/platform/tutorials/image-processing/decode.md index d1796a54..080018f1 100644 --- a/docs/platform/tutorials/image-processing/decode.md +++ b/docs/platform/tutorials/image-processing/decode.md @@ -76,7 +76,7 @@ Using the following steps, update the default code so it decodes the web cam ima def on_stream_received_handler(stream_consumer: qx.StreamConsumer): # subscribe to new DataFrames being received # if you aren't familiar with DataFrames there are other callbacks available - # refer to the docs here: https://docs.quix.io/sdk/subscribe.html + # refer to the docs here: https://docs.quix.io/client-library/subscribe.html stream_consumer.events.on_data_received = on_event_data_received_handler # register the event data callback stream_consumer.timeseries.on_dataframe_received = on_dataframe_received_handler diff --git a/docs/platform/tutorials/train-and-deploy-ml/deploy-ml.md b/docs/platform/tutorials/train-and-deploy-ml/deploy-ml.md index 90090072..8ae53da6 100644 --- a/docs/platform/tutorials/train-and-deploy-ml/deploy-ml.md +++ b/docs/platform/tutorials/train-and-deploy-ml/deploy-ml.md @@ -62,7 +62,7 @@ Ensure you are logged into the Quix Portal You can edit and run the code from here or clone it to your computer and work locally. - See more about setting up your local environment [here](../../../sdk/python-setup.md). + See more about setting up your local environment [here](../../../client-library/python-setup.md). ### Upload the model diff --git a/docs/sdk-intro.md b/docs/sdk-intro.md index 4ce435af..7ee08d7d 100644 --- a/docs/sdk-intro.md +++ b/docs/sdk-intro.md @@ -1 +1 @@ -This file is replaced with the SDK Docs README.md file during the build \ No newline at end of file +This file is replaced with the Quix Streams README.md file during the build \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 23303853..bfda10e7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -66,7 +66,7 @@ nav: #ConnectorsGetInsertedHere - 'Troubleshooting': 'platform/troubleshooting/troubleshooting.md' - 'Security': 'platform/security/security.md' - - 'SDK': '!import https://github.com/quixio/quix-streams?branch=main' + - 'Client Library': '!import https://github.com/quixio/quix-streams?branch=main' - API: - 'Index': 'apis/index.md' - 'Data Catalogue API': From 3537c59a4c105a9fc8ffe2c47438e219cffdd672 Mon Sep 17 00:00:00 2001 From: tbedford Date: Fri, 17 Mar 2023 14:47:43 +0000 Subject: [PATCH 2/2] [fix] - rename stub file --- docs/{sdk-intro.md => client-library-intro.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{sdk-intro.md => client-library-intro.md} (100%) diff --git a/docs/sdk-intro.md b/docs/client-library-intro.md similarity index 100% rename from docs/sdk-intro.md rename to docs/client-library-intro.md