doc: remove cargo-sync-readme

Use build.rs instead

.github/workflows/ci.yml

@@ -138,23 +138,6 @@ jobs:
           command: fmt
           args: --all -- --check
 
-  readme-sync:
-    name: Sync Readme
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: ./rusqlite_migration
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions-rs/toolchain@v1
-        with:
-          profile: minimal
-          toolchain: stable
-          override: true
-      - uses: Swatinem/rust-cache@v2
-      - run: cargo install cargo-sync-readme
-      - run: cargo sync-readme --check
-
   mutation-tests:
     name: Mutation tests
     runs-on: ubuntu-latest

README.md

@@ -36,7 +36,7 @@ end_insert -->
 {{< /rawhtml >}}
 end_insert -->
 
-<!-- cargo-sync-readme start -->
+<!-- rustdoc start -->
 
 Rusqlite Migration is a simple and performant schema migration library for [rusqlite](https://lib.rs/crates/rusqlite).
 
@@ -108,21 +108,8 @@ fn migrations_test() {
 
 Contributions (documentation or code improvements in particular) are welcome, see [contributing](https://cj.rs/docs/contribute/)!
 
-Please note that if you want to change something in the main README.md file, you likely need to
-edit the top comment in `rusqlite_migration/src/lib.rs` and then run [`cargo
-sync-readme`][sync-readme] from the `rusqlite_migration` subdirectory (the one that contain
-`src`). This command copies the content of the top comment to the `README.md` file, keeping
-`lib.rs` and the `README.md` sync. The only exception to this is when you want to edit
-something outside of the `<!-- cargo-sync-readme start -->` and
-`<!-- cargo-sync-readme end -->` markers.
-
-[sync-readme]: https://github.com/phaazon/cargo-sync-readme
-
 ## Acknowledgments
 
 I would like to thank all the contributors, as well as the authors of the dependencies this crate uses.
 
-
-<!-- cargo-sync-readme end -->
-
 Thanks to [Migadu](https://www.migadu.com/) for offering a discounted service to support this project. It is not an endorsement by Migadu though.

rusqlite_migration/build.rs

@@ -0,0 +1,30 @@
+use std::{
+    env,
+    fs::{read_to_string, File},
+    io::{self, BufWriter, Write},
+};
+
+fn main() {
+    let readme_path = env::var("CARGO_PKG_README").unwrap();
+    println!("cargo:rerun-if-changed={readme_path}");
+
+    let out_dir = env::var("OUT_DIR").unwrap();
+    let readme_for_rustdoc = File::create(format!("{out_dir}/readme_for_rustdoc.md")).unwrap();
+    let mut out = BufWriter::new(readme_for_rustdoc);
+
+    let readme = read_to_string(readme_path).unwrap();
+    readme
+        .lines()
+        .skip_while(|line| line != &"<!-- rustdoc start -->")
+        .skip(1) // Discard the pattern line
+        .try_fold(0, |acc, line| -> Result<usize, io::Error> {
+            Ok(acc + out.write(line.as_bytes())? + out.write(&[b'\n'])?)
+        })
+        .map(|i| {
+            assert!(
+                i > 3_000,
+                "the size of the documentation produced from the README.md file is suspisciously small"
+            )
+        })
+        .unwrap();
+}

rusqlite_migration/src/lib.rs

@@ -16,91 +16,8 @@ limitations under the License.
 
 #![forbid(unsafe_code)]
 #![warn(missing_docs)]
-
-//! Rusqlite Migration is a simple and performant schema migration library for [rusqlite](https://lib.rs/crates/rusqlite).
-//!
-//! * **Performance**:
-//!     * *Fast database opening*: to keep track of the current migration state, most tools create one or more tables in the database. These tables require parsing by SQLite and are queried with SQL statements. This library uses the [`user_version`][uv] value instead. It’s much lighter as it is just an integer at a [fixed offset][uv_offset] in the SQLite file.
-//!     * *Fast compilation*: this crate is very small and does not use macros to define the migrations.
-//! * **Simplicity**: this crate strives for simplicity. Just define a set of SQL statements as strings in your Rust code. Add more SQL statements over time as needed. No external CLI required. Additionally, rusqlite_migration works especially well with other small libraries complementing rusqlite, like [serde_rusqlite][].
-//!
-//! [diesel_migrations]: https://lib.rs/crates/diesel_migrations
-//! [pgfine]: https://crates.io/crates/pgfine
-//! [movine]: https://crates.io/crates/movine
-//! [uv]: https://sqlite.org/pragma.html#pragma_user_version
-//! [uv_offset]: https://www.sqlite.org/fileformat.html#user_version_number
-//! [serde_rusqlite]: https://crates.io/crates/serde_rusqlite
-//!
-//! ## Example
-//!
-//! Here, we define SQL statements to run with [`Migrations::new()`][migrations_new] and run these (if necessary) with [`Migrations::to_latest()`][migrations_to_latest].
-//!
-//! [migrations_new]: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.Migrations.html#method.new
-//! [migrations_to_latest]: https://docs.rs/rusqlite_migration/latest/rusqlite_migration/struct.Migrations.html#method.to_latest
-//!
-//! ``` rust
-//! use rusqlite::{params, Connection};
-//! use rusqlite_migration::{Migrations, M};
-//!
-//! // 1️⃣ Define migrations
-//! let migrations = Migrations::new(vec![
-//!     M::up("CREATE TABLE friend(name TEXT NOT NULL);"),
-//!     // In the future, add more migrations here:
-//!     //M::up("ALTER TABLE friend ADD COLUMN email TEXT;"),
-//! ]);
-//!
-//! let mut conn = Connection::open_in_memory().unwrap();
-//!
-//! // Apply some PRAGMA, often better to do it outside of migrations
-//! conn.pragma_update(None, "journal_mode", &"WAL").unwrap();
-//!
-//! // 2️⃣ Update the database schema, atomically
-//! migrations.to_latest(&mut conn).unwrap();
-//!
-//! // 3️⃣ Use the database 🥳
-//! conn.execute("INSERT INTO friend (name) VALUES (?1)", params!["John"])
-//!     .unwrap();
-//! ```
-//!
-//! Please see the [examples](https://github.com/cljoly/rusqlite_migrate/tree/master/examples) folder for more, in particular:
-//! - `async` migrations in the [`quick_start_async.rs`][quick_start_async] file
-//! - migrations with multiple SQL statements (using for instance `r#"…"` or `include_str!(…)`)
-//! - use of lazy_static
-//! - migrations to previous versions (downward migrations)
-//!
-//! [quick_start_async]: https://github.com/cljoly/rusqlite_migrate/tree/master/examples/quick_start_async.rs
-//!
-//! I’ve also made a [cheatsheet of SQLite pragma for improved performance and consistency](https://cj.rs/blog/sqlite-pragma-cheatsheet-for-performance-and-consistency/).
-//!
-//! ### Built-in tests
-//!
-//! To test that the migrations are working, you can add this in your test module:
-//!
-//! ``` rust
-//! #[test]
-//! fn migrations_test() {
-//!     assert!(MIGRATIONS.validate().is_ok());
-//! }
-//! ```
-//!
-//! ## Contributing
-//!
-//! Contributions (documentation or code improvements in particular) are welcome, see [contributing](https://cj.rs/docs/contribute/)!
-//!
-//! Please note that if you want to change something in the main README.md file, you likely need to
-//! edit the top comment in `rusqlite_migration/src/lib.rs` and then run [`cargo
-//! sync-readme`][sync-readme] from the `rusqlite_migration` subdirectory (the one that contain
-//! `src`). This command copies the content of the top comment to the `README.md` file, keeping
-//! `lib.rs` and the `README.md` sync. The only exception to this is when you want to edit
-//! something outside of the `<!-- cargo-sync-readme start -->` and
-//! `<!-- cargo-sync-readme end -->` markers.
-//!
-//! [sync-readme]: https://github.com/phaazon/cargo-sync-readme
-//!
-//! ## Acknowledgments
-//!
-//! I would like to thank all the contributors, as well as the authors of the dependencies this crate uses.
-//!
+// The doc is extracted from the README.md file at build time
+#![doc = include_str!(concat!(env!("OUT_DIR"), "/readme_for_rustdoc.md"))]
 
 use log::{debug, info, trace, warn};
 use rusqlite::{Connection, OptionalExtension, Transaction};