Skip to content

Commit 197f4e0

Browse files
curquizacurquiza
authored
Generated README (#32)
* Update comment * Add scripts * Add generation of the README * Update CONTRIBUTING.md * Update script * Update script * Add getting started as generated code * Update README * Update README template after rebasing * Update tpl after rebase * Move useful in src/lib/rs for the docs.rs * Add check before pushing the release: the version number should also be in lib.rs * Move back WASM part in lib.rs for docs.rs
1 parent d95baea commit 197f4e0

File tree

9 files changed

+198
-56
lines changed

9 files changed

+198
-56
lines changed

‎.github/scripts/check-release.sh

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,15 @@
22

33
# Checking if current tag matches the package version
44
current_tag=$(echo $GITHUB_REF | tr -d 'refs/tags/v')
5-
file_tag=$(grep '^version = ' Cargo.toml | cut -d '=' -f 2 | tr -d '"' | tr -d ' ')
6-
if [ "$current_tag" != "$file_tag" ]; then
5+
file1='Cargo.toml'
6+
file2='src/lib.rs'
7+
8+
file_tag1=$(grep '^version = ' $file1 | cut -d '=' -f 2 | tr -d '"' | tr -d ' ')
9+
file_tag2=$(grep '//! meilisearch-sdk = ' $file2 | cut -d '=' -f 2 | tr -d '"' | tr -d ' ')
10+
if [ "$current_tag" != "$file_tag1" ] || [ "$current_tag" != "$file_tag2" ]; then
711
echo "Error: the current tag does not match the version in package file(s)."
8-
echo "$current_tag vs $file_tag"
12+
echo "$file1: found $file_tag1 - expected $current_tag"
13+
echo "$file2: found $file_tag2 - expected $current_tag"
914
exit 1
1015
fi
1116

‎.github/workflows/rust.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ jobs:
1515

1616
steps:
1717
- uses: actions/checkout@v2
18+
- name: Check the README.md file is up-to-date
19+
run: sh scripts/check-readme.sh
1820
- name: Run linter (clippy)
1921
# Will fail when encountering warnings
2022
run: |

‎CONTRIBUTING.md

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,28 @@ $ rustup update
6060
$ rustup component add clippy
6161
```
6262

63+
### Update the README
64+
65+
The README is generated. Please do not update manually the `README.md` file.
66+
67+
Instead, update the `README.tpl` and `src/lib.rs` files, and run:
68+
69+
```sh
70+
$ sh scripts/update-readme.sh
71+
```
72+
73+
Then, add the generated `README.md` file to your git commit.
74+
75+
You can check the current `README.md` is up-to-date by running:
76+
77+
```sh
78+
$ sh scripts/check-readme.sh
79+
# To see the diff
80+
$ sh scripts/check-readme.sh --diff
81+
```
82+
83+
If it's not, the CI will fail on your PR.
84+
6385
### Release Process
6486

6587
MeiliSearch tools follow the [Semantic Versioning Convention](https://semver.org/).
@@ -80,12 +102,20 @@ About this automation:
80102

81103
#### How to Publish the Release
82104

83-
Make a PR modifying the file [`Cargo.toml`](/Cargo.toml) with the right version.
105+
Make a PR modifying the file [`Cargo.toml`](/Cargo.toml):
84106

85107
```toml
86108
version = "X.X.X"
87109
```
88110

111+
and the [`src/lib.rs`](/src/lib.rs):
112+
113+
```rust
114+
//! meilisearch-sdk = "X.X.X"
115+
```
116+
117+
with the right version.
118+
89119
Once the changes are merged on `master`, you can publish the current draft release via the [GitHub interface](https://github.com/meilisearch/meilisearch-rust/releases).
90120

91121
A GitHub Action will be triggered and push the package to [crates.io](https://crates.io/crates/meilisearch-sdk).

‎README.md

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
<!-- Do NOT update manually the README.md file -->
2+
<!-- Update the README.tpl or src/lib.rs files instead, and run: -->
3+
<!-- sh scripts/update-readme.sh -->
4+
15
<p align="center">
26
<img src="https://res.cloudinary.com/meilisearch/image/upload/v1587402338/SDKs/meilisearch_rust.svg" alt="MeiliSearch-Dotnet" width="200" height="200" />
37
</p>
@@ -25,12 +29,12 @@
2529

2630
**MeiliSearch Rust** is a client for **MeiliSearch** written in Rust. **MeiliSearch** is a powerful, fast, open-source, easy to use and deploy search engine. Both searching and indexing are highly customizable. Features such as typo-tolerance, filters, and synonyms are provided out-of-the-box.
2731

28-
### Table of Contents
32+
## Table of Contents
2933

3034
- [🔧 Installation](#-installation)
3135
- [🚀 Getting Started](#-getting-started)
32-
- [🤖 Compatibility with MeiliSearch](#-compatibility-with-meilisearch)
3336
- [🌐 Running in the Browser with WASM](#-running-in-the-browser-with-wasm)
37+
- [🤖 Compatibility with MeiliSearch](#-compatibility-with-meilisearch)
3438
- [⚙️ Development Workflow and Contributing](#️-development-workflow-and-contributing)
3539

3640
## 🔧 Installation
@@ -39,14 +43,14 @@ To use `meilisearch-sdk`, add this to your `Cargo.toml`:
3943

4044
```toml
4145
[dependencies]
42-
meilisearch-sdk = "0.2"
46+
meilisearch-sdk = "0.2.0"
4347
```
4448

4549
The following optional dependencies may also be useful:
4650

4751
```toml
4852
tokio = { version = "0.2", features = ["macros"] }
49-
serde = { version="1.0", features = ["derive"] }
53+
serde = { version = "1.0", features = ["derive"] }
5054
```
5155

5256
Since this crate is async, you have to run your program in the [tokio](https://crates.io/crates/tokio) runtime. When targetting Wasm, the browser will replace tokio.
@@ -67,11 +71,8 @@ $ docker run -it --rm -p 7700:7700 getmeili/meilisearch:latest ./meilisearch --m
6771

6872
NB: you can also download MeiliSearch from **Homebrew** or **APT**.
6973

70-
7174
## 🚀 Getting Started
7275

73-
Here is a quickstart for a search request (please follow the [installation](#-installation) steps before)
74-
7576
```rust
7677
use meilisearch_sdk::{document::*, client::*, search::*};
7778
use serde::{Serialize, Deserialize};
@@ -121,12 +122,7 @@ Output:
121122
[Book { book_id: 4, title: "Harry Potter and the Half-Blood Prince" }]
122123
```
123124

124-
## 🤖 Compatibility with MeiliSearch
125-
126-
This package is compatible with the following MeiliSearch versions:
127-
- `v0.13.0`
128-
129-
## 🌐 Running in the Browser with WASM
125+
### 🌐 Running in the Browser with WASM
130126

131127
This crate fully supports WASM.
132128

@@ -136,6 +132,11 @@ However, making a program intended to run in a web browser requires a **very** d
136132

137133
WARNING: `meilisearch-sdk` will panic if no Window is available (ex: Web extension).
138134

135+
## 🤖 Compatibility with MeiliSearch
136+
137+
This package is compatible with the following MeiliSearch versions:
138+
- `v0.13.X`
139+
139140
## ⚙️ Development Workflow and Contributing
140141

141142
Any new contribution is more than welcome in this project!

‎README.tpl

Lines changed: 51 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,55 @@
1-
# {{crate}} [![Latest Version]][crates.io]
2-
[Latest Version]: https://img.shields.io/crates/v/meilisearch-sdk
3-
[crates.io]: https://crates.io/crates/meilisearch-sdk
1+
<!-- Do NOT update manually the README.md file -->
2+
<!-- Update the README.tpl or src/lib.rs files instead, and run: -->
3+
<!-- sh scripts/update-readme.sh -->
4+
5+
<p align="center">
6+
<img src="https://res.cloudinary.com/meilisearch/image/upload/v1587402338/SDKs/meilisearch_rust.svg" alt="MeiliSearch-Dotnet" width="200" height="200" />
7+
</p>
8+
9+
<h1 align="center">MeiliSearch Rust SDK (WIP)</h1>
10+
11+
<h4 align="center">
12+
<a href="https://github.com/meilisearch/MeiliSearch">MeiliSearch</a> |
13+
<a href="https://www.meilisearch.com">Website</a> |
14+
<a href="https://blog.meilisearch.com">Blog</a> |
15+
<a href="https://twitter.com/meilisearch">Twitter</a> |
16+
<a href="https://docs.meilisearch.com">Documentation</a> |
17+
<a href="https://docs.meilisearch.com/faq">FAQ</a>
18+
</h4>
19+
20+
<p align="center">
21+
<a href="https://crates.io/crates/meilisearch-sdk"><img src="https://img.shields.io/crates/v/meilisearch-sdk.svg" alt="crates.io"></a>
22+
<a href="https://github.com/meilisearch/meilisearch-rust/actions"><img src="https://github.com/meilisearch/meilisearch-rust/workflows/Test/badge.svg?branch=master" alt="Tests"></a>
23+
<a href="https://github.com/meilisearch/meilisearch-rust/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-informational" alt="License"></a>
24+
<a href="https://github.com/meilisearch/MeiliSearch/discussions" alt="Discussions"><img src="https://img.shields.io/badge/github-discussions-red" /></a>
25+
<a href="https://slack.meilisearch.com"><img src="https://img.shields.io/badge/slack-MeiliSearch-blue.svg?logo=slack" alt="Slack"></a>
26+
</p>
27+
28+
<p align="center">⚡ Lightning Fast, Ultra Relevant, and Typo-Tolerant Search Engine MeiliSearch client written in Rust</p>
29+
30+
**MeiliSearch Rust** is a client for **MeiliSearch** written in Rust. **MeiliSearch** is a powerful, fast, open-source, easy to use and deploy search engine. Both searching and indexing are highly customizable. Features such as typo-tolerance, filters, and synonyms are provided out-of-the-box.
31+
32+
## Table of Contents
33+
34+
- [🔧 Installation](#-installation)
35+
- [🚀 Getting Started](#-getting-started)
36+
- [🌐 Running in the Browser with WASM](#-running-in-the-browser-with-wasm)
37+
- [🤖 Compatibility with MeiliSearch](#-compatibility-with-meilisearch)
38+
- [⚙️ Development Workflow and Contributing](#️-development-workflow-and-contributing)
439

540
{{readme}}
641

7-
Current version: {{version}}
42+
## 🤖 Compatibility with MeiliSearch
43+
44+
This package is compatible with the following MeiliSearch versions:
45+
- `v0.13.X`
46+
47+
## ⚙️ Development Workflow and Contributing
48+
49+
Any new contribution is more than welcome in this project!
50+
51+
If you want to know more about the development workflow or want to contribute, please visit our [contributing guidelines](/CONTRIBUTING.md) for detailed instructions!
52+
53+
<hr>
854

9-
License: {{license}}
55+
**MeiliSearch** provides and maintains many **SDKs and Integration tools** like this one. We want to provide everyone with an **amazing search experience for any kind of project**. If you want to contribute, make suggestions, or just know what's going on right now, visit us in the [integration-guides](https://github.com/meilisearch/integration-guides) repository.

‎scripts/check-readme.sh

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
#!/bin/sh
2+
3+
# Checking that cargo is installed
4+
command -v cargo > /dev/null 2>&1
5+
if [ "$?" -ne 0 ]; then
6+
echo 'You must install cargo to make this script working.'
7+
echo 'See https://doc.rust-lang.org/cargo/getting-started/installation.html'
8+
exit 1
9+
fi
10+
11+
# Installing cargo-readme if it's not installed yet
12+
cargo install cargo-readme
13+
14+
# Comparing the generated README and the current one
15+
curent_readme="README.md"
16+
generated_readme="README.md_tmp"
17+
cargo readme > "$generated_readme"
18+
19+
# Exiting with the right message
20+
echo ''
21+
diff "$curent_readme" "$generated_readme" > /dev/null 2>&1
22+
if [ "$?" = 0 ]; then
23+
echo "OK"
24+
rm -f "$generated_readme"
25+
exit 0
26+
else
27+
echo "The current README.md is not up-to-date with the template."
28+
29+
# Displaying the diff if the --diff flag is activated
30+
if [ "$1" = '--diff' ]; then
31+
echo 'Diff found:'
32+
diff "$curent_readme" "$generated_readme"
33+
else
34+
echo 'To see the diff, run:'
35+
echo ' $ sh scripts/check-readme.sh --diff'
36+
echo 'To update the README, run:'
37+
echo ' $ sh scripts/update-readme.sh'
38+
fi
39+
40+
rm -f "$generated_readme"
41+
exit 1
42+
fi

‎scripts/update-readme.sh

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
#!/bin/sh
2+
3+
# Checking that cargo is installed
4+
command -v cargo > /dev/null 2>&1
5+
if [ "$?" -ne 0 ]; then
6+
echo 'You must install cargo to make this script working.'
7+
echo 'See https://doc.rust-lang.org/cargo/getting-started/installation.html'
8+
exit
9+
fi
10+
11+
# Installing cargo-readme if it's not installed yet
12+
cargo install cargo-readme
13+
14+
# Generating the README.md file
15+
cargo readme > README.md

‎src/client.rs

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,7 @@ pub struct Client<'a> {
1313
impl<'a> Client<'a> {
1414
/// Create a client using the specified server.
1515
/// Don't put a '/' at the end of the host.
16-
/// If you are not in production mode, the second field is useless.
17-
/// In production mode, see [the documentation](https://docs.meilisearch.com/references/keys.html) to get the needed key.
18-
///
16+
/// In production mode, see [the documentation about authentication](https://docs.meilisearch.com/guides/advanced_guides/authentication.html#authentication).
1917
/// # Example
2018
///
2119
/// ```

‎src/lib.rs

Lines changed: 34 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,41 @@
1-
//! MeiliSearch-sdk is an async client for [MeiliSearch](https://www.meilisearch.com/) written in Rust.
2-
//! [MeiliSearch](https://www.meilisearch.com/) is a powerful, fast, open-source, easy to use and deploy search engine.
3-
//! Both searching and indexing are highly customizable.
4-
//! Features such as typo-tolerance, filters, and synonyms are provided out-of-the-box.
1+
//! # 🔧 Installation
52
//!
6-
//! ## Table of Contents
7-
//! - [🔧 Installation](#-installation)
8-
//! - [🚀 Getting started](#-getting-started)
9-
//! - [🌐 Running in the browser with WASM](#-running-in-the-browser-with-wasm)
10-
//! - [🤖 Compatibility with MeiliSearch](#-compatibility-with-meilisearch)
3+
//! To use `meilisearch-sdk`, add this to your `Cargo.toml`:
114
//!
12-
//! # 🔧 Installation
5+
//! ```toml
6+
//! [dependencies]
7+
//! meilisearch-sdk = "0.2.0"
8+
//! ```
139
//!
14-
//! This crate requires a MeiliSearch server to run. See [here](https://docs.meilisearch.com/guides/advanced_guides/installation.html#download-and-launch) to install and run MeiliSearch.
10+
//! The following optional dependencies may also be useful:
1511
//!
16-
//! Then, put `meilisearch-sdk = "0.1"` in your Cargo.toml, as usual.
12+
//! ```toml
13+
//! tokio = { version = "0.2", features = ["macros"] }
14+
//! serde = { version = "1.0", features = ["derive"] }
15+
//! ```
1716
//!
18-
//! Since this crate is async, you have to run your program in the tokio runtime (cf the example below). You will need `tokio = { version = "0.2", features=["macros"] }` in your Cargo.toml. When targetting Wasm, the browser will replace tokio.
17+
//! Since this crate is async, you have to run your program in the [tokio](https://crates.io/crates/tokio) runtime. When targetting Wasm, the browser will replace tokio.
1918
//!
2019
//! Using this crate is possible without [serde](https://crates.io/crates/serde), but a lot of features require serde.
21-
//! Add `serde = {version="1.0", features=["derive"]}` in your Cargo.toml.
2220
//!
23-
//! # 🚀 Getting Started
21+
//! ## Run a MeiliSearch Instance
22+
//!
23+
//! This crate requires a MeiliSearch server to run.
24+
//!
25+
//! There are many easy ways to [download and run a MeiliSearch instance](https://docs.meilisearch.com/guides/advanced_guides/installation.html#download-and-launch).
26+
//!
27+
//! For example, if you use Docker:
28+
//! ```bash
29+
//! $ docker pull getmeili/meilisearch:latest # Fetch the latest version of MeiliSearch image from Docker Hub
30+
//! $ docker run -it --rm -p 7700:7700 getmeili/meilisearch:latest ./meilisearch --master-key=masterKey
31+
//! ```
32+
//!
33+
//! NB: you can also download MeiliSearch from **Homebrew** or **APT**.
2434
//!
25-
//! Here is a quickstart for a search request (please follow the [installation](#-installation) steps before)
35+
//! # 🚀 Getting Started
2636
//!
27-
//! ```rust
28-
//! use meilisearch_sdk::{document::*, indexes::*, client::*, search::*};
37+
//! ```
38+
//! use meilisearch_sdk::{document::*, client::*, search::*};
2939
//! use serde::{Serialize, Deserialize};
3040
//!
3141
//! #[derive(Serialize, Deserialize, Debug)]
@@ -49,7 +59,7 @@
4959
//! let client = Client::new("http://localhost:7700", "masterKey");
5060
//!
5161
//! // Get the index called "books"
52-
//! let mut books = client.get_or_create("books").await.unwrap();
62+
//! let books = client.get_or_create("books").await.unwrap();
5363
//!
5464
//! // Add some books in the index
5565
//! books.add_documents(&[
@@ -73,22 +83,15 @@
7383
//! [Book { book_id: 4, title: "Harry Potter and the Half-Blood Prince" }]
7484
//! ```
7585
//!
76-
//! # 🌐 Running in the browser with WASM
86+
//! ## 🌐 Running in the Browser with WASM
7787
//!
78-
//! This crate fully supports WASM. The only difference between the WASM and the native version is that the native version has one more variant (Error::Http) in the Error enum. That should not matter so much but we could add this variant in WASM too.
79-
//! However, making a program intended to run in a web browser requires a **very** different design than a CLI program. To see an example of a simple Rust web app using meilisearch, see the [tutorial (not available yet)]().
88+
//! This crate fully supports WASM.
8089
//!
81-
//! WARNING: `meilisearch-sdk` will panic if no Window is available (ex: Web extension).
82-
//!
83-
//! # 🤖 Compatibility with MeiliSearch
90+
//! The only difference between the WASM and the native version is that the native version has one more variant (`Error::Http`) in the Error enum. That should not matter so much but we could add this variant in WASM too.
8491
//!
85-
//! This crate is currently supporting MeiliSearch v11.0 and will be maintained.
92+
//! However, making a program intended to run in a web browser requires a **very** different design than a CLI program. To see an example of a simple Rust web app using MeiliSearch, see the [tutorial (not available yet)]().
8693
//!
87-
//! # Running the tests
88-
//!
89-
//! All the tests are documentation tests.
90-
//! Since they are all making operations on the MeiliSearch server, running all the tests simultaneously would cause panics.
91-
//! To run the tests one by one, run `cargo test -- --test-threads=1`.
94+
//! WARNING: `meilisearch-sdk` will panic if no Window is available (ex: Web extension).
9295
9396
/// Module containing the Client struct.
9497
pub mod client;

0 commit comments

Comments
 (0)