This is an automated email from the ASF dual-hosted git repository.
mgrigorov pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/avro.git
The following commit(s) were added to refs/heads/master by this push:
new 7ff2d7a07 AVRO-3849: [Rust] Use cargo-rdme instead of cargo-readme
(#2475)
7ff2d7a07 is described below
commit 7ff2d7a075debbf7e038f0a4f0674cb312d5473a
Author: Kousuke Saruta <[email protected]>
AuthorDate: Mon Sep 4 15:55:02 2023 +0900
AVRO-3849: [Rust] Use cargo-rdme instead of cargo-readme (#2475)
* AVRO-3849: [Rust] Use cargo-rdme instead of cargo-readme
* Mark json as the syntax of a schema example
---
lang/rust/.cargo-rdme.toml | 19 +++++++++++++++++++
lang/rust/Makefile | 2 +-
lang/rust/avro/README.md | 19 ++++++++-----------
lang/rust/avro/src/lib.rs | 34 ++++++++++++++++++++++++++++++++--
4 files changed, 60 insertions(+), 14 deletions(-)
diff --git a/lang/rust/.cargo-rdme.toml b/lang/rust/.cargo-rdme.toml
new file mode 100644
index 000000000..3f27313be
--- /dev/null
+++ b/lang/rust/.cargo-rdme.toml
@@ -0,0 +1,19 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+readme-path = "avro/README.md"
+workspace-project = "apache-avro"
\ No newline at end of file
diff --git a/lang/rust/Makefile b/lang/rust/Makefile
index c948b8511..4a903c1c6 100644
--- a/lang/rust/Makefile
+++ b/lang/rust/Makefile
@@ -85,7 +85,7 @@ doc-local:
.PHONY: readme
readme:
- cargo readme > README.md
+ cargo rdme
# BUILDING
diff --git a/lang/rust/avro/README.md b/lang/rust/avro/README.md
index beddf0f84..4155785a2 100644
--- a/lang/rust/avro/README.md
+++ b/lang/rust/avro/README.md
@@ -24,7 +24,9 @@
[](https://docs.rs/apache-avro)
[](https://github.com/apache/avro/blob/master/LICENSE.txt)
-A library for working with [Apache Avro](https://avro.apache.org/) in Rust
language.
+<!-- cargo-rdme start -->
+
+A library for working with [Apache Avro](https://avro.apache.org/) in Rust.
Please check our [documentation](https://docs.rs/apache-avro) for examples,
tutorials and API reference.
@@ -33,7 +35,7 @@ data structures and a compact, fast, binary data format.
All data in Avro is schematized, as in the following example:
-```
+```json
{
"type": "record",
"name": "test",
@@ -95,11 +97,10 @@ version = "x.y"
features = ["xz"]
```
-
## Upgrading to a newer minor version
The library is still in beta, so there might be backward-incompatible changes
between minor
-versions. If you have troubles upgrading, check the [version upgrade
guide](migration_guide.md).
+versions. If you have troubles upgrading, check the [version upgrade
guide](https://github.com/apache/avro/blob/master/lang/rust/migration_guide.md).
## Defining a schema
@@ -189,7 +190,6 @@ associated type provided by the library to specify the data
we want to serialize
```rust
use apache_avro::types::Record;
use apache_avro::Writer;
-#
// a writer needs a schema and something to write to
let mut writer = Writer::new(&schema, Vec::new());
@@ -276,12 +276,10 @@ You must enable the `bzip` feature to use this codec.
* **Xz**: uses [xz2](https://github.com/alexcrichton/xz2-rs) compression
library.
You must enable the `xz` feature to use this codec.
-
To specify a codec to use to compress data, just specify it while creating a
`Writer`:
```rust
use apache_avro::Writer;
use apache_avro::Codec;
-#
let mut writer = Writer::with_codec(&schema, Vec::new(), Codec::Deflate);
```
@@ -293,7 +291,6 @@ codec:
```rust
use apache_avro::Reader;
-#
// reader creation can fail in case the input to read from is not
Avro-compatible or malformed
let reader = Reader::new(&input[..]).unwrap();
```
@@ -303,7 +300,6 @@ the data has been written with, we can just do as the
following:
```rust
use apache_avro::Schema;
use apache_avro::Reader;
-#
let reader_raw_schema = r#"
{
@@ -342,7 +338,6 @@ We can just read directly instances of `Value` out of the
`Reader` iterator:
```rust
use apache_avro::Reader;
-#
let reader = Reader::new(&input[..]).unwrap();
// value is a Result of an Avro Value in case the read operation fails
@@ -434,7 +429,7 @@ fn main() -> Result<(), Error> {
`apache-avro` also supports the logical types listed in the [Avro
specification](https://avro.apache.org/docs/current/spec.html#Logical+Types):
1. `Decimal` using the
[`num_bigint`](https://docs.rs/num-bigint/0.2.6/num_bigint) crate
-1. UUID using the [`uuid`](https://docs.rs/uuid/0.8.1/uuid) crate
+1. UUID using the [`uuid`](https://docs.rs/uuid/1.0.0/uuid) crate
1. Date, Time (milli) as `i32` and Time (micro) as `i64`
1. Timestamp (milli and micro) as `i64`
1. Duration as a custom type with `months`, `days` and `millis` accessor
methods each of which returns an `i32`
@@ -642,6 +637,8 @@ let readers_schema = Schema::parse_str(r#"{"type": "array",
"items":"int"}"#).un
assert_eq!(false, SchemaCompatibility::can_read(&writers_schema,
&readers_schema));
```
+<!-- cargo-rdme end -->
+
## Minimal supported Rust version
1.65.0
diff --git a/lang/rust/avro/src/lib.rs b/lang/rust/avro/src/lib.rs
index 146a08a2e..cde0251c5 100644
--- a/lang/rust/avro/src/lib.rs
+++ b/lang/rust/avro/src/lib.rs
@@ -24,7 +24,7 @@
//!
//! All data in Avro is schematized, as in the following example:
//!
-//! ```text
+//! ```json
//! {
//! "type": "record",
//! "name": "test",
@@ -62,10 +62,34 @@
//! features = ["snappy"]
//! ```
//!
+//! Or in case you want to leverage the **Zstandard** codec:
+//!
+//! ```toml
+//! [dependencies.apache-avro]
+//! version = "x.y"
+//! features = ["zstandard"]
+//! ```
+//!
+//! Or in case you want to leverage the **Bzip2** codec:
+//!
+//! ```toml
+//! [dependencies.apache-avro]
+//! version = "x.y"
+//! features = ["bzip"]
+//! ```
+//!
+//! Or in case you want to leverage the **Xz** codec:
+//!
+//! ```toml
+//! [dependencies.apache-avro]
+//! version = "x.y"
+//! features = ["xz"]
+//! ```
+//!
//! # Upgrading to a newer minor version
//!
//! The library is still in beta, so there might be backward-incompatible
changes between minor
-//! versions. If you have troubles upgrading, check the [version upgrade
guide](migration_guide.md).
+//! versions. If you have troubles upgrading, check the [version upgrade
guide](https://github.com/apache/avro/blob/master/lang/rust/migration_guide.md).
//!
//! # Defining a schema
//!
@@ -260,6 +284,12 @@
//! * **Snappy**: uses Google's [Snappy](http://google.github.io/snappy/)
compression library. Each
//! compressed block is followed by the 4-byte, big-endianCRC32 checksum of
the uncompressed data in
//! the block. You must enable the `snappy` feature to use this codec.
+//! * **Zstandard**: uses Facebook's
[Zstandard](https://facebook.github.io/zstd/) compression library.
+//! You must enable the `zstandard` feature to use this codec.
+//! * **Bzip2**: uses [BZip2](https://sourceware.org/bzip2/) compression
library.
+//! You must enable the `bzip` feature to use this codec.
+//! * **Xz**: uses [xz2](https://github.com/alexcrichton/xz2-rs) compression
library.
+//! You must enable the `xz` feature to use this codec.
//!
//! To specify a codec to use to compress data, just specify it while creating
a `Writer`:
//! ```
