From 70b870925aeb01410f7887f6b7d703e23d0d7d52 Mon Sep 17 00:00:00 2001 From: "ChenYing Kuo (CY)" Date: Wed, 18 Dec 2024 16:52:21 +0800 Subject: [PATCH] Add CI for checking markdown format. (#325) Signed-off-by: ChenYing Kuo --- .github/workflows/ci.yml | 11 ++++++- .markdownlint.yaml | 7 +++++ README.md | 66 +++++++++++++++++++++------------------- examples/README.md | 21 ++++++++----- 4 files changed, 66 insertions(+), 39 deletions(-) create mode 100644 .markdownlint.yaml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8eaa79b8..0b186734 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -59,6 +59,15 @@ jobs: - name: Gradle Test run: gradle jvmTest --info + 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 # from branches where specific status checks have passed. These checks are @@ -67,7 +76,7 @@ jobs: ci: name: CI status checks runs-on: ubuntu-latest - needs: build + needs: [build, markdown_lint] if: always() steps: - name: Check whether all jobs pass diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 00000000..144a0959 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,7 @@ +{ + "MD013": false, # Line length limitation + "MD024": false, # Allow multiple headings with the same content + "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 c78acb55..f44467ef 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,6 @@ [![License](https://img.shields.io/badge/License-EPL%202.0-blue)](https://choosealicense.com/licenses/epl-2.0/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) - # Eclipse Zenoh The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute. @@ -16,36 +15,34 @@ 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. - ---- # Kotlin Kotlin API - This repository provides a Kotlin binding based on the main [Zenoh implementation written in Rust](https://github.com/eclipse-zenoh/zenoh). The code relies on the Zenoh JNI native library, which written in Rust and communicates with the Kotlin layer via the Java Native Interface (JNI). ## Documentation -The documentation of the API is published at https://eclipse-zenoh.github.io/zenoh-kotlin/index.html. +The documentation of the API is published [here](https://eclipse-zenoh.github.io/zenoh-kotlin/index.html). Alternatively, you can build it locally as [explained below](#building-the-documentation). ---- + # How to import :warning: Note nº1: **About the released packages** The released packages can be found in the "packages" section of this repository, or in the links below: -* [Android packages](https://github.com/eclipse-zenoh/zenoh-kotlin/packages/1968034/versions) -* [JVM packages](https://github.com/eclipse-zenoh/zenoh-kotlin/packages/2016733/versions) + +- [Android packages](https://github.com/eclipse-zenoh/zenoh-kotlin/packages/1968034/versions) +- [JVM packages](https://github.com/eclipse-zenoh/zenoh-kotlin/packages/2016733/versions) These are 'nightly' packages that need to be imported as explained in the following sections of this README. We plan to publish our packages into Maven central in the very short term. - - ## Android Android For this first version we have published a [Github package](https://github.com/eclipse-zenoh/zenoh-kotlin/packages/1968034) with the library which can be imported on your projects. @@ -84,6 +81,7 @@ implementation("org.eclipse.zenoh:zenoh-kotlin-android:1.0.0") ### Platforms The library targets the following platforms: + - x86 - x86_64 - arm @@ -102,8 +100,9 @@ Zenoh is a communications protocol, therefore the permissions required are: ``` ---- -# Java JVM +---- + +## Java JVM Similar to Android, we have published a Github package to import on your projects. @@ -140,26 +139,27 @@ implementation("io.zenoh:zenoh-kotlin-jvm:1.0.0") For the moment, the library targets the following platforms: - - x86_64-unknown-linux-gnu - - aarch64-unknown-linux-gnu - - x86_64-apple-darwin - - aarch64-apple-darwin - - x86_64-pc-windows-msvc - +- x86_64-unknown-linux-gnu +- aarch64-unknown-linux-gnu +- x86_64-apple-darwin +- aarch64-apple-darwin +- x86_64-pc-windows-msvc ---- +---- # How to build it ## What you need Basically: -* Rust ([Installation guide](https://doc.rust-lang.org/cargo/getting-started/installation.html)) -* Kotlin ([Installation guide](https://kotlinlang.org/docs/getting-started.html#backend)) -* Gradle ([Installation guide](https://gradle.org/install/)) + +- Rust ([Installation guide](https://doc.rust-lang.org/cargo/getting-started/installation.html)) +- Kotlin ([Installation guide](https://kotlinlang.org/docs/getting-started.html#backend)) +- Gradle ([Installation guide](https://gradle.org/install/)) and in case of targetting Android you'll also need: -* Android SDK ([Installation guide](https://developer.android.com/about/versions/11/setup-sdk)) + +- Android SDK ([Installation guide](https://developer.android.com/about/versions/11/setup-sdk)) ## JVM JVM @@ -179,7 +179,7 @@ Once we have published the package, we should be able to find it under `~/.m2/re Finally, in the `build.gradle.kts` file of the project where you intend to use this library, add mavenLocal to the list of repositories and add zenoh-kotlin as a dependency: -``` +```kotlin repositories { mavenCentral() mavenLocal() @@ -202,14 +202,14 @@ It can be set up by using Android Studio (go to `Preferences > Languages & Frame or alternatively it can be found [here](https://developer.android.com/ndk/downloads). The native platforms we are going to target are the following ones: -``` + - x86 - x86_64 - arm - arm64 -``` Therefore, if they are not yet already added to the Rust toolchain, run: + ```bash rustup target add armv7-linux-androideabi; \ rustup target add i686-linux-android; \ @@ -219,8 +219,8 @@ rustup target add x86_64-linux-android to install them. - So, in order to publish the library onto Maven Local, run: + ```bash gradle -Pandroid=true publishAndroidReleasePublicationToMavenLocal ``` @@ -230,7 +230,8 @@ publish the library, containing the native binaries. You should now be able to see the package under `~/.m2/repository/io/zenoh/zenoh-kotlin-android/1.0.0` with the following files: -``` + +```raw zenoh-kotlin-android-1.0.0-sources.jar zenoh-kotlin-android-1.0.0.aar zenoh-kotlin-android-1.0.0.module @@ -241,7 +242,8 @@ Now the library is published on maven local, let's now see how to import it into First, we need to indicate we want to look into mavenLocal for our library, so in your top level `build.gradle.kts` you need to specify the `mavenLocal` repository: -``` + +```kotlin repositories { mavenCentral() ... @@ -249,14 +251,15 @@ repositories { } ``` -Then in your app's `build.gradle.kts` filen add the dependency: -``` +Then in your app's `build.gradle.kts` file add the dependency: + +```kotlin implementation("io.zenoh:zenoh-kotlin-android:1.0.0") ``` And finally, do not forget to add the required internet permissions on your manifest! -``` +```xml ``` @@ -268,6 +271,7 @@ And that was it! You can now import the code from the `io.zenoh` package and use Because it's a Kotlin project, we use [Dokka](https://kotlinlang.org/docs/dokka-introduction.html) to generate the documentation. In order to build it, run: + ```bash gradle zenoh-kotlin:dokkaHtml ``` @@ -298,7 +302,7 @@ causes the logs to appear in standard output. The log levels are the ones from Rust: `trace`, `info`, `debug`, `error` and `warn`. ---- +---- # Examples diff --git a/examples/README.md b/examples/README.md index 9b627bf6..e2796d30 100644 --- a/examples/README.md +++ b/examples/README.md @@ -4,19 +4,18 @@ ## Start instructions - - ```bash - gradle --args="" +gradle --args="" ``` for instance ```bash - gradle ZPub --args="-h" +gradle ZPub --args="-h" ``` will return + ```bash > Task :examples:ZPub Usage: zpub [] @@ -44,12 +43,13 @@ The connect and listen parameters (that are common to all the examples) accept m For instance: ```bash - gradle ZPub --args="-l tcp/localhost:7447 -l tcp/localhost:7448 -l tcp/localhost:7449" +gradle ZPub --args="-l tcp/localhost:7447 -l tcp/localhost:7448 -l tcp/localhost:7449" ``` There is the possibility to provide a Zenoh config file as follows + ```bash - gradle ZPub --args="-c path/to/config.json5" +gradle ZPub --args="-c path/to/config.json5" ``` In that case, any other provided configuration parameters through the command line interface will not be taken into consideration. @@ -57,7 +57,7 @@ In that case, any other provided configuration parameters through the command li One last comment regarding Zenoh logging for the examples, remember it can be enabled through the environment variable `RUST_LOG` as follows: ```bash - RUST_LOG= gradle ZPub +RUST_LOG= gradle ZPub ``` where `` can be either `info`, `trace`, `debug`, `warn` or `error`. @@ -76,12 +76,15 @@ Usage: ```bash gradle ZPub ``` + or + ```bash gradle ZPub --args="-k demo/example/test -v 'hello world'" ``` ### ZSub + Creates a subscriber with a key expression. The subscriber will be notified of each put made on any key expression matching the subscriber's key expression, and will print this notification. @@ -91,7 +94,9 @@ Usage: ```bash gradle ZSub ``` + or + ```bash gradle ZSub --args="-k demo/example/test" ``` @@ -105,6 +110,7 @@ will receive this query and reply with paths/values that will be received by the ```bash gradle ZGet ``` + or ```bash @@ -129,6 +135,7 @@ gradle ZPut --args="-k demo/example/put -v 'Put from Kotlin!'" ``` ### ZDelete + Performs a Delete operation into a path/value into Zenoh. Usage: