diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0b59d58..274e958 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -77,6 +77,15 @@ jobs: - name: Transpile Library run: | yarn run build + + markdown_lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: DavidAnson/markdownlint-cli2-action@v18 + with: + config: '.markdownlint.yaml' + globs: '**/README.md' # NOTE: In GitHub repository settings, the "Require status checks to pass # before merging" branch protection rule ensures that commits are only merged @@ -86,7 +95,7 @@ jobs: ci: name: CI status checks runs-on: ubuntu-latest - needs: [build-rs, build-ts] + needs: [build-rs, build-ts, markdown_lint] if: always() steps: - name: Check whether all jobs pass diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..12f7379 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,6 @@ +{ + "MD013": false, # Line length limitation + "MD033": false, # Enable Inline HTML + "MD041": false, # Allow first line heading + "MD045": false, # Allow Images have no alternate text +} \ No newline at end of file diff --git a/README.md b/README.md index c450d0d..0d94a0f 100644 --- a/README.md +++ b/README.md @@ -114,13 +114,13 @@ The file `EXAMPLE_CONFIG.json5` references the `zenoh-plugin-remote-api\EXAMPLE_ 1. Make sure that the following utilities are available on your platform. -- [NPM](https://www.npmjs.com/package/npm) -- [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#debian-stable) -- [Typescript](https://www.typescriptlang.org/download/) + - [NPM](https://www.npmjs.com/package/npm) + - [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#debian-stable) + - [Typescript](https://www.typescriptlang.org/download/) 2. Navigate to the directory `zenoh-ts` -1. Run the commands: +3. Run the commands: ```sh yarn install diff --git a/zenoh-plugin-remote-api/README.md b/zenoh-plugin-remote-api/README.md index 0cc75aa..afdfe7a 100644 --- a/zenoh-plugin-remote-api/README.md +++ b/zenoh-plugin-remote-api/README.md @@ -14,20 +14,24 @@ Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and computations Check the website [zenoh.io](http://zenoh.io) and the [roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed information. ------------------------------- + # Remote API Plugin In Zenoh, the remote API plugin is an library loaded into a Zenohd instance at start up, which allows the creation of a Session, declaration of zenoh resources (Subscribers, Publishers, Queryables) remotely via websockets, for runtime environments where it is currently unsupported to run a zenoh binary. The Remote API was designed to support the Typescript Zenoh bindings, running in a browser. ------------------------------- + ## **Examples of usage** Prerequisites: - - You have a zenoh router (`zenohd`) installed, and the `libzenoh_plugin_remote_api.so` library file is available in `~/.zenoh/lib` or `~/target/debug`. + +- You have a zenoh router (`zenohd`) installed, and the `libzenoh_plugin_remote_api.so` library file is available in `~/.zenoh/lib` or `~/target/debug`. ### **Setup via a JSON5 configuration file** - - Create a `zenoh.json5` configuration file containing for example: +- Create a `zenoh.json5` configuration file containing for example: + ```json5 { mode: "router", @@ -43,11 +47,11 @@ Prerequisites: } ``` - - Run the zenoh router with: - `zenohd -c EXAMPLE_CONFIG.json5` +- Run the zenoh router with: `zenohd -c EXAMPLE_CONFIG.json5` ------------------------------- + ## How to build it > :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active development. When you build from git, make sure you also build from git any other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.). It may happen that some changes in git are not compatible with the most recent packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in mantaining compatibility between the various git repositories in the Zenoh project. @@ -55,7 +59,7 @@ Prerequisites: At first, install [Cargo and Rust](https://doc.rust-lang.org/cargo/getting-started/installation.html). If you already have the Rust toolchain installed, make sure it is up-to-date with: ```bash -$ rustup update +rustup update ``` > :warning: **WARNING** :warning: : As Rust doesn't have a stable ABI, the backend library should be @@ -64,40 +68,47 @@ Otherwise, incompatibilities in memory mapping of shared types between `zenohd` To know the Rust version you're `zenohd` has been built with, use the `--version` option. -### Example with a downloaded zenohd: +### Example with a downloaded zenohd + ```bash $ zenohd --version zenohd v1.0.0-beta.2 built with rustc 1.75.0 (82e1608df 2023-12-21) ``` + Here, `zenohd` is version `v1.0.0-beta.2` has been built with the rustc version `1.75.0`. Install and use this same toolchain with the following command: ```bash -$ rustup default 1.75.0 +rustup default 1.75.0 ``` And edit the update `Cargo.toml` file to make all the `zenoh` dependencies to use the same version number: + ```toml zenoh = { version = "v1.0.0-beta.2", features = [ "unstable" ] } ``` Then build the plugin: + ```bash -$ cargo build --release --all-targets -p zenoh-plugin-remote-api +cargo build --release --all-targets -p zenoh-plugin-remote-api ``` +### Example with a version built from sources -### Example with a version built from sources: ```bash $ zenohd --version zenohd v1.0.0-beta.2 built with rustc 1.75.0 (82e1608df 2023-12-21) ``` + Here, `zenohd` version is `v1.0.0-beta.2` where: + - `v1.0.0-beta.2` means it's a development version for the future `v1.0.0` release - `82e1608df` indicates the commit hash - And it has been built with the `rustc` version `1.75.0`. + Install and use this same toolchain with the following command: ```bash -$ rustup default 1.75.0 -``` \ No newline at end of file +rustup default 1.75.0 +``` diff --git a/zenoh-ts/README.md b/zenoh-ts/README.md index 9bbcec7..4bfcc2b 100644 --- a/zenoh-ts/README.md +++ b/zenoh-ts/README.md @@ -17,7 +17,7 @@ Check the website [zenoh.io](http://zenoh.io) and the [roadmap](https://github.c # Typescript/Javascript API -This repository provides a Typscript / Javascript binding through the use of the `remote-api-plugin` in this repo. +This repository provides a Typscript / Javascript binding through the use of the `remote-api-plugin` in this repo. The long term plan is to use zenoh [Zenoh written in Rust](https://github.com/eclipse-zenoh/zenoh) to target WASM. In its current state, it is not possible to compile Zenoh (Rust) to target WASM, and will need to undergo a fair amount of refactoring before that can happen. @@ -27,38 +27,34 @@ In its current state, it is not possible to compile Zenoh (Rust) to target WASM, > :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active development. When you build from git, make sure you also build from git any other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.). It may happen that some changes in git are not compatible with the most recent packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in maintaining compatibility between the various git repositories in the Zenoh project. -1. Make sure that the following utilities are available on your platform. - - [NPM](https://www.npmjs.com/package/npm) - - [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#debian-stable) - - [Typescript](https://www.typescriptlang.org/download/) +1. Make sure that the following utilities are available on your platform. + + - [NPM](https://www.npmjs.com/package/npm) + - [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#debian-stable) + - [Typescript](https://www.typescriptlang.org/download/) 2. Navigate to the directory `zenoh-ts` 3. Run the commands: ```bash - yarn install - # - yarn run build +yarn install +yarn run build ``` ## Adding Typescript to your application -The TypeScript library can be install from the command line: +The TypeScript library can be install from the command line: `npm install @eclipse-zenoh/zenoh-ts@0.0.8` Or added via package.json -`"@eclipse-zenoh/zenoh-ts": "0.0.8" ` +`"@eclipse-zenoh/zenoh-ts": "0.0.8"` Note: In order to add this library to your project you must log into the github npm repository, please refer to this link for more information [Accessing github NPM](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-with-a-personal-access-token) - -[zenoh]: https://github.com/eclipse-zenoh/zenoh - - ## Generating Documentation 1. Make sure that the [typedoc](https://typedoc.org/) dependency is installed. @@ -68,7 +64,7 @@ please refer to this link for more information [Accessing github NPM](https://do 3. Run the commands: ```bash - npx typedoc src/index.ts +npx typedoc src/index.ts ``` ## Build + run the examples @@ -77,26 +73,27 @@ The most simple way to run examples is to install [deno](https://deno.com/), and 1. Install [deno](https://deno.com/) 2. Navigate to the `/zenoh-ts/examples` directory -3. Install `zenoh-ts` library by running `yarn install` +3. Install `zenoh-ts` library by running `yarn install` 4. Start a `zenohd` instance with the Remote API plugin running `zenohd --config EXAMPLE CONFIG.json` -```json -{ - mode: 'router', - plugins_loading: { - enabled: true, - search_dirs: ['./target/debug', '~/.zenoh/lib'] - }, - plugins: { - remote_api: { - websocket_port: '10000', + + ```json + { + mode: 'router', + plugins_loading: { + enabled: true, + search_dirs: ['./target/debug', '~/.zenoh/lib'] + }, + plugins: { + remote_api: { + websocket_port: '10000', + } + } } - } -} -``` + ``` + 5. Then run the examples by running `yarn run `, i.e. `yarn example src/z_sub.ts` This will start an instance of Deno running the example. The application will attempt to connect to a `websocket_port` : `10000` where the Remote API plugin is expected to be running. -The javascript runtime [deno](https://deno.com/) is expected be consistent with the browser. -Note: This library does not support NodeJS - +The javascript runtime [deno](https://deno.com/) is expected be consistent with the browser. +Note: This library does not support NodeJS diff --git a/zenoh-ts/examples/chat/README.md b/zenoh-ts/examples/chat/README.md index a3022b1..a45f8d4 100644 --- a/zenoh-ts/examples/chat/README.md +++ b/zenoh-ts/examples/chat/README.md @@ -24,4 +24,4 @@ verify that the zenoh-ts library is ready to be used in browser without addition Note though that not all dependent libraries follows this rule. Some of them (e.g. `channel-ts`) can be used directly in browser only after proper repacking. So when using importmap approach -the dependent libraries are loaded from the [jspm.io](https://jspm.org/cdn/jspm-io) \ No newline at end of file +the dependent libraries are loaded from the [jspm.io](https://jspm.org/cdn/jspm-io) diff --git a/zenoh-ts/examples/deno/README.md b/zenoh-ts/examples/deno/README.md index 9063c2f..61b69e2 100644 --- a/zenoh-ts/examples/deno/README.md +++ b/zenoh-ts/examples/deno/README.md @@ -13,14 +13,14 @@ Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and computations Check the website [zenoh.io](http://zenoh.io) and the [roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed information. -:warning: Note: This library does not support NodeJS. +:warning: Note: This library does not support NodeJS. To run on the backend its recommended either to use [deno](https://deno.com/) or check out the differnt language bindings --- # Typescript/Javascript API -This repository provides a Typscript / Javascript binding through the use of the `remote-api-plugin` in this repo. +This repository provides a Typscript / Javascript binding through the use of the `remote-api-plugin` in this repo. The long term plan is to use zenoh [Zenoh written in Rust](https://github.com/eclipse-zenoh/zenoh) to target WASM. In its current state, it is not possible to compile Zenoh (Rust) to target WASM, and will need to undergo a fair amount of refactoring before that can happen. @@ -30,21 +30,25 @@ In its current state, it is not possible to compile Zenoh (Rust) to target WASM, The example project is a Web project using [Vite](https://vite.dev/) -In order to run the example project the user must: +In order to run the example project the user must: + 1. Build the Typescript Library 2. Build + Run the remote-api-plugin 3. Build + Run the examples - ### 1. Build the Typescript Library + From project root directory: + 1. Navigate to the `/zenoh-ts` directory 2. Build the `zenoh-ts` bindings by running `yarn install && yarn build` ### 2. Build + Run the remote-api-plugin + From project root directory: + 1. Build the plugin by running `cargo build` -2. Run an instance of `zenohd` loading the plugin `zenohd --config ./zenoh-plugin-remote-api/EXAMPLE_CONFIG.json5 ` with the following config +2. Run an instance of `zenohd` loading the plugin `zenohd --config ./zenoh-plugin-remote-api/EXAMPLE_CONFIG.json5` with the following config ```json5 { @@ -60,6 +64,7 @@ From project root directory: }, } ``` + The latest version of `zenohd` can be build from source from [zenoh](https://github.com/eclipse-zenoh/zenoh/) or downloaded from the [release](https://github.com/eclipse-zenoh/zenoh/releases) page for your platform. Keep this terminal running while building and running the example below @@ -70,15 +75,15 @@ The most simple way to run examples is to install [deno](https://deno.com/), and 1. Install [deno](https://deno.com/) 2. Navigate to the `/zenoh-ts/examples` directory -3. Install `zenoh-ts` library by running `yarn install` +3. Install `zenoh-ts` library by running `yarn install` 4. Then run the examples by running `yarn run `, i.e. `yarn example src/z_sub.ts` This will start an instance of Deno running the example. The application will attempt to connect to a `websocket_port` : `10000` where the Remote API plugin is expected to be running. -The javascript runtime [deno](https://deno.com/) is expected be consistent with the browser. -Note: This library does not support NodeJS +The javascript runtime [deno](https://deno.com/) is expected be consistent with the browser. +Note: This library does not support NodeJS ### Clean projects -To reset state of the project from the top level directory run -`cargo clean && cd zenoh-ts && yarn clean && cd examples && yarn clean` \ No newline at end of file +To reset state of the project from the top level directory run +`cargo clean && cd zenoh-ts && yarn clean && cd examples && yarn clean`