diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 676feeb..a99659b 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -7,6 +7,6 @@ - [ ] Linted code using clippy - [ ] with reqwest feature: `cargo clippy --manifest-path influxdb/Cargo.toml --all-targets --no-default-features --features use-serde,derive,reqwest-client -- -D warnings` - [ ] with surf feature: `cargo clippy --manifest-path influxdb/Cargo.toml --all-targets --no-default-features --features use-serde,derive,hyper-client -- -D warnings` -- [ ] Updated README.md using `cargo readme -r influxdb -t ../README.tpl > README.md` +- [ ] Updated README.md using `cargo doc2readme -p influxdb --expand-macros` - [ ] Reviewed the diff. Did you leave any print statements or unnecessary comments? - [ ] Any unfinished work that warrants a separate issue captured in an issue with a TODO code comment diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index 410376e..494d437 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -13,9 +13,10 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - - uses: dtolnay/rust-toolchain@nightly - - run: bash ./auxiliary/update_cargo-readme.sh - - run: bash ./auxiliary/check_readme_consistency.sh + - uses: docker://ghcr.io/msrd0/cargo-doc2readme:nightly + with: + entrypoint: cargo + args: doc2readme -p influxdb --expand-macros --check # this checks that there are no clippy lints clippy: diff --git a/README.tpl b/README.j2 similarity index 88% rename from README.tpl rename to README.j2 index 6e09e78..ff9a594 100644 --- a/README.tpl +++ b/README.j2 @@ -32,4 +32,9 @@ {{readme}} -@ 2020 Gero Gerke and [contributors](https://github.com/influxdb-rs/influxdb-rust/graphs/contributors). +@ 2020 Gero Gerke and [contributors]. + + [contributors]: https://github.com/influxdb-rs/influxdb-rust/graphs/contributors +{%- if links != "" %} +{{ links }} +{% endif -%} diff --git a/README.md b/README.md index acea862..6e5f3a2 100644 --- a/README.md +++ b/README.md @@ -30,33 +30,36 @@

-This library is a work in progress. This means a feature you might need is not implemented -yet or could be handled better. +This library is a work in progress. This means a feature you might need is not implemented yet or could be handled better. + +Pull requests are always welcome. See [Contributing][__link0] and [Code of Conduct][__link1]. For a list of past changes, see [CHANGELOG.md][__link2]. -Pull requests are always welcome. See [Contributing](https://github.com/influxdb-rs/influxdb-rust/blob/main/CONTRIBUTING.md) and [Code of Conduct](https://github.com/influxdb-rs/influxdb-rust/blob/main/CODE_OF_CONDUCT.md). For a list of past changes, see [CHANGELOG.md](https://github.com/influxdb-rs/influxdb-rust/blob/main/CHANGELOG.md). ### Currently Supported Features -- Reading and Writing to InfluxDB -- Optional Serde Support for Deserialization -- Running multiple queries in one request (e.g. `SELECT * FROM weather_berlin; SELECT * FROM weather_london`) -- Writing single or multiple measurements in one request (e.g. `WriteQuery` or `Vec` argument) -- Authenticated and Unauthenticated Connections -- `async`/`await` support -- `#[derive(InfluxDbWriteable)]` Derive Macro for Writing / Reading into Structs -- `GROUP BY` support -- Tokio and async-std support (see example below) or [available backends](https://github.com/influxdb-rs/influxdb-rust/blob/main/influxdb/Cargo.toml) -- Swappable HTTP backends ([see below](#Choice-of-HTTP-backend)) + - Reading and Writing to InfluxDB + - Optional Serde Support for Deserialization + - Running multiple queries in one request (e.g. `SELECT * FROM weather_berlin; SELECT * FROM weather_london`) + - Writing single or multiple measurements in one request (e.g. `WriteQuery` or `Vec` argument) + - Authenticated and Unauthenticated Connections + - `async`/`await` support + - `#[derive(InfluxDbWriteable)]` Derive Macro for Writing / Reading into Structs + - `GROUP BY` support + - Tokio and async-std support (see example below) or [available backends][__link3] + - Swappable HTTP backends ([see below](#Choice-of-HTTP-backend)) + ## Quickstart Add the following to your `Cargo.toml` + ```toml -influxdb = { version = "0.6", features = ["derive"] } +influxdb = { version = "0.6.0", features = ["derive"] } ``` -For an example with using Serde deserialization, please refer to [serde_integration](crate::integrations::serde_integration) +For an example with using Serde deserialization, please refer to [serde_integration][__link4] + ```rust use influxdb::{Client, Query, Timestamp, ReadQuery}; @@ -104,46 +107,82 @@ async fn main() { } ``` -For further examples, check out the Integration Tests in `tests/integration_tests.rs` -in the repository. +For further examples, check out the Integration Tests in `tests/integration_tests.rs` in the repository. + ## Choice of HTTP backend To communicate with InfluxDB, you can choose the HTTP backend to be used configuring the appropriate feature. We recommend sticking with the default reqwest-based client, unless you really need async-std compatibility. -- **[hyper](https://github.com/hyperium/hyper)** (through reqwest, used by default), with [rustls](https://github.com/ctz/rustls) - ```toml - influxdb = { version = "0.6", features = ["derive"] } - ``` - -- **[hyper](https://github.com/hyperium/hyper)** (through reqwest), with native TLS (OpenSSL) - ```toml - influxdb = { version = "0.6", default-features = false, features = ["derive", "use-serde", "reqwest-client"] } - ``` - -- **[hyper](https://github.com/hyperium/hyper)** (through surf), use this if you need tokio 0.2 compatibility - ```toml - influxdb = { version = "0.6", default-features = false, features = ["derive", "use-serde", "curl-client"] } - ``` -- **[curl](https://github.com/alexcrichton/curl-rust)**, using [libcurl](https://curl.se/libcurl/) - ```toml - influxdb = { version = "0.6", default-features = false, features = ["derive", "use-serde", "curl-client"] } - ``` -- **[async-h1](https://github.com/http-rs/async-h1)** with native TLS (OpenSSL) - ```toml - influxdb = { version = "0.6", default-features = false, features = ["derive", "use-serde", "h1-client"] } - ``` -- **[async-h1](https://github.com/http-rs/async-h1)** with [rustls](https://github.com/ctz/rustls) - ```toml - influxdb = { version = "0.6", default-features = false, features = ["derive", "use-serde", "h1-client-rustls"] } - ``` -- WebAssembly's `window.fetch`, via `web-sys` and **[wasm-bindgen](https://github.com/rustwasm/wasm-bindgen)** - ```toml - influxdb = { version = "0.6", default-features = false, features = ["derive", "use-serde", "wasm-client"] } - ``` + - **[hyper][__link5]** (through reqwest, used by default), with [rustls][__link6] + ```toml + influxdb = { version = "0.6.0", features = ["derive"] } + ``` + + + - **[hyper][__link7]** (through reqwest), with native TLS (OpenSSL) + ```toml + influxdb = { version = "0.6.0", default-features = false,features = ["derive", "use-serde", "reqwest-client"] } + ``` + + + - **[hyper][__link8]** (through surf), use this if you need tokio 0.2 compatibility + ```toml + influxdb = { version = "0.6.0", default-features = false,features = ["derive", "use-serde", "hyper-client"] } + ``` + + + - **[curl][__link9]**, using [libcurl][__link10] + ```toml + influxdb = { version = "0.6.0", default-features = false,features = ["derive", "use-serde", "curl-client"] } + ``` + + + - **[async-h1][__link11]** with native TLS (OpenSSL) + ```toml + influxdb = { version = "0.6.0", default-features = false,features = ["derive", "use-serde", "h1-client"] } + ``` + + + - **[async-h1][__link12]** with [rustls][__link13] + ```toml + influxdb = { version = "0.6.0", default-features = false,features = ["derive", "use-serde", "h1-client-rustls"] } + ``` + + + - WebAssembly’s `window.fetch`, via `web-sys` and **[wasm-bindgen][__link14]** + ```toml + influxdb = { version = "0.6.0", default-features = false,features = ["derive", "use-serde", "wasm-client"] } + ``` + + + ## License -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![License: MIT][__link15]][__link16] + + + +@ 2020 Gero Gerke and [contributors]. + + [contributors]: https://github.com/influxdb-rs/influxdb-rust/graphs/contributors + [__cargo_doc2readme_dependencies_info]: ggGkYW0BYXSEG-eS3ZnLalPKG8RSyE7OgxOuG5N_7FO9S6I9G5Bq0rFyX93cYXKEGyBiJeIUzlcaG-d2lJz85cl_G-crYZ-mhyAvG6Wf1YbqYiItYWSBgmhpbmZsdXhkYmUwLjYuMA + [__link0]: https://github.com/influxdb-rs/influxdb-rust/blob/main/CONTRIBUTING.md + [__link1]: https://github.com/influxdb-rs/influxdb-rust/blob/main/CODE_OF_CONDUCT.md + [__link10]: https://curl.se/libcurl/ + [__link11]: https://github.com/http-rs/async-h1 + [__link12]: https://github.com/http-rs/async-h1 + [__link13]: https://github.com/ctz/rustls + [__link14]: https://github.com/rustwasm/wasm-bindgen + [__link15]: https://img.shields.io/badge/License-MIT-yellow.svg + [__link16]: https://opensource.org/licenses/MIT + [__link2]: https://github.com/influxdb-rs/influxdb-rust/blob/main/CHANGELOG.md + [__link3]: https://github.com/influxdb-rs/influxdb-rust/blob/main/influxdb/Cargo.toml + [__link4]: https://docs.rs/influxdb/0.6.0/influxdb/?search=integrations::serde_integration + [__link5]: https://github.com/hyperium/hyper + [__link6]: https://github.com/ctz/rustls + [__link7]: https://github.com/hyperium/hyper + [__link8]: https://github.com/hyperium/hyper + [__link9]: https://github.com/alexcrichton/curl-rust -@ 2020 Gero Gerke and [contributors](https://github.com/influxdb-rs/influxdb-rust/graphs/contributors). diff --git a/auxiliary/check_readme_consistency.sh b/auxiliary/check_readme_consistency.sh deleted file mode 100755 index f5c120a..0000000 --- a/auxiliary/check_readme_consistency.sh +++ /dev/null @@ -1,14 +0,0 @@ -#!/bin/bash - -cargo readme -r influxdb -t ../README.tpl > README.md.expected - -diff README.md README.md.expected - -if [ $? -eq 0 ] -then - echo 'README.md is up to date!' - exit 0 -else - echo 'README.md out of date. Run "cargo readme -r influxdb -t ../README.tpl > README.md" and commit again.' - exit 1 -fi diff --git a/auxiliary/update_cargo-readme.sh b/auxiliary/update_cargo-readme.sh deleted file mode 100755 index d2180d1..0000000 --- a/auxiliary/update_cargo-readme.sh +++ /dev/null @@ -1,11 +0,0 @@ -#!/usr/bin/bash - -our_version=$(cargo readme -V | perl -ne 'print $1 while /v([\d.]+)/g') -last_version=$(cargo search --color=never cargo-readme | perl -ne 'print $1 while /^cargo-readme = "([\d.]+)"/g') - -if [ "$our_version" == "$last_version" ]; then - echo Version $our_version is of cargo-readme is installed and up to date. -else - echo "Install cargo-readme" - cargo install cargo-readme -fi diff --git a/influxdb/src/lib.rs b/influxdb/src/lib.rs index f947ae9..282dca2 100644 --- a/influxdb/src/lib.rs +++ b/influxdb/src/lib.rs @@ -20,9 +20,7 @@ //! //! Add the following to your `Cargo.toml` //! -//! ```toml -//! influxdb = { version = "0.6", features = ["derive"] } -//! ``` +#![doc = cargo_toml!(indent="", "derive")] //! //! For an example with using Serde deserialization, please refer to [serde_integration](crate::integrations::serde_integration) //! @@ -80,35 +78,19 @@ //! To communicate with InfluxDB, you can choose the HTTP backend to be used configuring the appropriate feature. We recommend sticking with the default reqwest-based client, unless you really need async-std compatibility. //! //! - **[hyper](https://github.com/hyperium/hyper)** (through reqwest, used by default), with [rustls](https://github.com/ctz/rustls) -//! ```toml -//! influxdb = { version = "0.6", features = ["derive"] } -//! ``` -//! +#![doc = cargo_toml!(indent="\t", "derive")] //! - **[hyper](https://github.com/hyperium/hyper)** (through reqwest), with native TLS (OpenSSL) -//! ```toml -//! influxdb = { version = "0.6", default-features = false, features = ["derive", "use-serde", "reqwest-client"] } -//! ``` -//! +#![doc = cargo_toml!(indent="\t", default-features = false, "derive", "use-serde", "reqwest-client")] //! - **[hyper](https://github.com/hyperium/hyper)** (through surf), use this if you need tokio 0.2 compatibility -//! ```toml -//! influxdb = { version = "0.6", default-features = false, features = ["derive", "use-serde", "curl-client"] } -//! ``` +#![doc = cargo_toml!(indent="\t", default-features = false, "derive", "use-serde", "hyper-client")] //! - **[curl](https://github.com/alexcrichton/curl-rust)**, using [libcurl](https://curl.se/libcurl/) -//! ```toml -//! influxdb = { version = "0.6", default-features = false, features = ["derive", "use-serde", "curl-client"] } -//! ``` +#![doc = cargo_toml!(indent="\t", default-features = false, "derive", "use-serde", "curl-client")] //! - **[async-h1](https://github.com/http-rs/async-h1)** with native TLS (OpenSSL) -//! ```toml -//! influxdb = { version = "0.6", default-features = false, features = ["derive", "use-serde", "h1-client"] } -//! ``` +#![doc = cargo_toml!(indent="\t", default-features = false, "derive", "use-serde", "h1-client")] //! - **[async-h1](https://github.com/http-rs/async-h1)** with [rustls](https://github.com/ctz/rustls) -//! ```toml -//! influxdb = { version = "0.6", default-features = false, features = ["derive", "use-serde", "h1-client-rustls"] } -//! ``` +#![doc = cargo_toml!(indent="\t", default-features = false, "derive", "use-serde", "h1-client-rustls")] //! - WebAssembly's `window.fetch`, via `web-sys` and **[wasm-bindgen](https://github.com/rustwasm/wasm-bindgen)** -//! ```toml -//! influxdb = { version = "0.6", default-features = false, features = ["derive", "use-serde", "wasm-client"] } -//! ``` +#![doc = cargo_toml!(indent="\t", default-features = false, "derive", "use-serde", "wasm-client")] //! //! # License //! @@ -118,6 +100,38 @@ #![allow(clippy::needless_lifetimes)] // False positive in client/mod.rs query fn #![forbid(bare_trait_objects)] +macro_rules! cargo_toml { + (indent=$indent:literal, $firstfeat:literal $(, $feature:literal)*) => { + cargo_toml_private!($indent, "", $firstfeat $(, $feature)*) + }; + + (indent=$indent:literal, default-features = false, $firstfeat:literal $(, $feature:literal)*) => { + cargo_toml_private!($indent, "default-features = false,", $firstfeat $(, $feature)*) + }; +} + +macro_rules! cargo_toml_private { + ($indent:literal, $deffeats:literal, $firstfeat:literal $(, $feature:literal)*) => { + concat!( + $indent, + "```toml\n", + + $indent, + "influxdb = { version = \"", + env!("CARGO_PKG_VERSION"), + "\", ", + $deffeats, + "features = [", + "\"", $firstfeat, "\"", + $(", \"", $feature, "\"",)* + "] }\n", + + $indent, + "```" + ) + }; +} + #[cfg(all(feature = "reqwest", feature = "surf"))] compile_error!("You need to choose between reqwest and surf; enabling both is not supported");