From d12215dbaeec88f336a522e807f9f4647f804d53 Mon Sep 17 00:00:00 2001 From: Noritada Kobayashi Date: Fri, 24 Jun 2022 19:53:40 +0900 Subject: [PATCH 1/4] Switch to mdBook (step 1) This commit includes only basic configurations. --- .gitignore | 3 +-- book.toml | 15 +++++++++++++++ 2 files changed, 16 insertions(+), 2 deletions(-) create mode 100644 book.toml diff --git a/.gitignore b/.gitignore index df6ce0e6..3006b271 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1 @@ -_book/ -node_modules/ +book/ diff --git a/book.toml b/book.toml new file mode 100644 index 00000000..5ff63bca --- /dev/null +++ b/book.toml @@ -0,0 +1,15 @@ +[book] +language = "en" +multilingual = false +src = "_src" +title = "Serde" + +[output.html] +git-repository-url = "https://github.com/serde-rs/serde-rs.github.io" +git-repository-icon = "fa-github" +edit-url-template = "https://github.com/serde-rs/serde-rs.github.io/edit/master/{path}" +cname = "serde.rs" + +[output.html.redirect] +"codegen.html" = "derive.html" +"borrow.html" = "lifetimes.html#borrowing-data-in-a-derived-impl" From d05d091b84b8c57871e2841d9c721a38d255eed4 Mon Sep 17 00:00:00 2001 From: Noritada Kobayashi Date: Sat, 25 Jun 2022 17:15:56 +0900 Subject: [PATCH 2/4] Switch to mdBook (step 2) This commit fixes Rust Playground integrations. --- _src/README.md | 1 - _src/attr-bound.md | 1 - _src/attr-default.md | 1 - _src/attr-rename.md | 1 - _src/attr-skip-serializing.md | 1 - _src/custom-date-format.md | 1 - _src/derive.md | 1 - _src/deserialize-map.md | 1 - _src/deserialize-struct.md | 1 - _src/enum-number.md | 2 +- _src/remote-derive.md | 6 +----- _src/stream-array.md | 1 - _src/string-or-struct.md | 2 +- _src/transcode.md | 2 +- _src/unit-testing.md | 2 +- book.toml | 3 +++ 16 files changed, 8 insertions(+), 19 deletions(-) diff --git a/_src/README.md b/_src/README.md index e494f058..b8f3d833 100644 --- a/_src/README.md +++ b/_src/README.md @@ -107,7 +107,6 @@ types in any of the above formats. For example `String`, `&str`, `usize`, macro to generate serialization implementations for structs in your own program. Using the derive macro goes like this: -!PLAYGROUND 72755f28f99afc95e01d63174b28c1f5 ```rust use serde::{Serialize, Deserialize}; diff --git a/_src/attr-bound.md b/_src/attr-bound.md index daed9003..236d8b63 100644 --- a/_src/attr-bound.md +++ b/_src/attr-bound.md @@ -10,7 +10,6 @@ As with most heuristics, this is not always right and Serde provides an escape hatch to replace the automatically generated bound by one written by the programmer. -!PLAYGROUND d2a50878ab69a5786f5a3a11a9de71ea ```rust use serde::{de, Deserialize, Deserializer}; diff --git a/_src/attr-default.md b/_src/attr-default.md index 1192d41a..16a901e6 100644 --- a/_src/attr-default.md +++ b/_src/attr-default.md @@ -1,6 +1,5 @@ # Default value for a field -!PLAYGROUND b238170d32f604295a1110ad912ef3ee ```rust use serde::Deserialize; diff --git a/_src/attr-rename.md b/_src/attr-rename.md index 14b0dea7..5d8e1490 100644 --- a/_src/attr-rename.md +++ b/_src/attr-rename.md @@ -1,6 +1,5 @@ # Serialize fields as camelCase -!PLAYGROUND b2852ed8e696999ccd9d2ac668b848bf ```rust use serde::Serialize; diff --git a/_src/attr-skip-serializing.md b/_src/attr-skip-serializing.md index ba25b6dd..ff0ee7e6 100644 --- a/_src/attr-skip-serializing.md +++ b/_src/attr-skip-serializing.md @@ -9,7 +9,6 @@ deserializing (see [Field Attributes: `skip`][attr-skip]). Likewise, use [attr-skip]: field-attrs.md#skip -!PLAYGROUND b65f4a90bb11285574a1917b0f5e10aa ```rust use serde::Serialize; diff --git a/_src/custom-date-format.md b/_src/custom-date-format.md index fe78c892..749b69e5 100644 --- a/_src/custom-date-format.md +++ b/_src/custom-date-format.md @@ -4,7 +4,6 @@ This uses the [`chrono`](https://github.com/chronotope/chrono) crate to serialize and deserialize JSON data containing a custom date format. The `with` attribute is used to provide the logic for handling the custom representation. -!PLAYGROUND 7185eb211a4822ce97184ae25fedda91 ```rust use chrono::{DateTime, Utc}; use serde::{Serialize, Deserialize}; diff --git a/_src/derive.md b/_src/derive.md index a1b646bb..f1173c17 100644 --- a/_src/derive.md +++ b/_src/derive.md @@ -46,7 +46,6 @@ serde_json = "1.0" Now the `src/main.rs` which uses Serde's custom derives: !FILENAME src/main.rs -!PLAYGROUND 1dbc76000e9875fac72c2865748842d7 ```rust use serde::{Serialize, Deserialize}; diff --git a/_src/deserialize-map.md b/_src/deserialize-map.md index 4e94ddee..5e50d8c4 100644 --- a/_src/deserialize-map.md +++ b/_src/deserialize-map.md @@ -1,6 +1,5 @@ # Implement Deserialize for a custom map type -!PLAYGROUND 72f10ca685c08f8afeb618efdabfed6a ```rust use std::fmt; use std::marker::PhantomData; diff --git a/_src/deserialize-struct.md b/_src/deserialize-struct.md index 0ad681db..8d32dd80 100644 --- a/_src/deserialize-struct.md +++ b/_src/deserialize-struct.md @@ -21,7 +21,6 @@ names. Instead there is a `Field` enum which is deserialized from a `&str`. The implementation supports two possible ways that a struct may be represented by a data format: as a seq like in Bincode, and as a map like in JSON. -!PLAYGROUND 2e212d29e38110fc3d8f22ff920712be ```rust use std::fmt; diff --git a/_src/enum-number.md b/_src/enum-number.md index b769488d..5c38410c 100644 --- a/_src/enum-number.md +++ b/_src/enum-number.md @@ -14,7 +14,7 @@ serde_json = "1.0" serde_repr = "0.1" ``` -```rust +```rust,noplayground use serde_repr::*; #[derive(Serialize_repr, Deserialize_repr, PartialEq, Debug)] diff --git a/_src/remote-derive.md b/_src/remote-derive.md index e86e90ba..024ac1f0 100644 --- a/_src/remote-derive.md +++ b/_src/remote-derive.md @@ -23,7 +23,6 @@ is that you have to provide a definition of the type for Serde's derive to process. At compile time, Serde will check that all the fields in the definition you provided match the fields in the remote type. -!PLAYGROUND 0a344c9dfc4cf965e66125ebdfbc48b8 ```rust // Pretend that this is somebody else's crate, not a module. mod other_crate { @@ -70,7 +69,6 @@ there is to it. If the remote type is a struct with one or more private fields, getters must be provided for the private fields and a conversion must be provided to construct the remote type. -!PLAYGROUND 02b8513dfb060b6580f998bac5a04a1a ```rust // Pretend that this is somebody else's crate, not a module. mod other_crate { @@ -141,7 +139,7 @@ rules as mentioned. The code ultimately generated by these remote derives are not `Serialize` and `Deserialize` impls but associated functions with the same signature. -```rust +```rust,noplayground # #![allow(dead_code)] # # use serde::Deserialize; @@ -170,7 +168,6 @@ struct DurationDef { Knowing this, the generated method can be invoked directly by passing a `Deserializer` implementation. -!PLAYGROUND 29cadbd640a231d5703564a666b0bc85 ```rust # #![allow(dead_code)] # @@ -196,7 +193,6 @@ let dur = DurationDef::deserialize(&mut de)?; Alternatively we can write a top-level newtype wrapper as a private helper for deserializing the remote type. -!PLAYGROUND 159da6ebf3a3573b8bd7f3bc2246026c ```rust # #![allow(dead_code)] # diff --git a/_src/stream-array.md b/_src/stream-array.md index 6d013b3a..d84c0305 100644 --- a/_src/stream-array.md +++ b/_src/stream-array.md @@ -5,7 +5,6 @@ without holding the whole array in memory all at once. This approach can be adapted to handle a variety of other situations in which data needs to be processed while being deserialized instead of after. -!PLAYGROUND 270186a56b8321704dc45001fdfa3c92 ```rust use serde::{Deserialize, Deserializer}; use serde::de::{self, Visitor, SeqAccess}; diff --git a/_src/string-or-struct.md b/_src/string-or-struct.md index 3f84a991..ff07471b 100644 --- a/_src/string-or-struct.md +++ b/_src/string-or-struct.md @@ -23,7 +23,7 @@ We can use Rust's [`FromStr`](https://doc.rust-lang.org/std/str/trait.FromStr.html) trait and Serde's `deserialize_with` attribute to handle this pattern in a general way. -```rust +```rust,noplayground use std::collections::BTreeMap as Map; use std::fmt; use std::marker::PhantomData; diff --git a/_src/transcode.md b/_src/transcode.md index 9fa5918b..93c67f64 100644 --- a/_src/transcode.md +++ b/_src/transcode.md @@ -14,7 +14,7 @@ This example implements the equivalent of Go's [`json.Compact`](https://golang.org/pkg/encoding/json/#Compact) function which removes insignificant whitespace from a JSON string in a streaming way. -```rust +```rust,noplayground use std::io; fn main() { diff --git a/_src/unit-testing.md b/_src/unit-testing.md index c8f5e4cd..5eb94b02 100644 --- a/_src/unit-testing.md +++ b/_src/unit-testing.md @@ -18,7 +18,7 @@ test expected failure conditions. Here is an example from the [`linked-hash-map`](https://github.com/contain-rs/linked-hash-map) crate. -```rust +```rust,noplayground # #[allow(unused_imports)] use linked_hash_map::LinkedHashMap; # diff --git a/book.toml b/book.toml index 5ff63bca..ed6316d3 100644 --- a/book.toml +++ b/book.toml @@ -4,6 +4,9 @@ multilingual = false src = "_src" title = "Serde" +[rust] +edition = "2018" + [output.html] git-repository-url = "https://github.com/serde-rs/serde-rs.github.io" git-repository-icon = "fa-github" From 1f89fb7f262be8701e4e3ac55ec0b4b40d59e9b3 Mon Sep 17 00:00:00 2001 From: Noritada Kobayashi Date: Sat, 25 Jun 2022 18:04:36 +0900 Subject: [PATCH 3/4] Switch to mdBook (step 3) This commit includes notation changes. --- _src/README.md | 13 +++---------- _src/derive.md | 9 ++++----- {img => _src/img}/github.svg | 0 {img => _src/img}/rustdoc.svg | 0 4 files changed, 7 insertions(+), 15 deletions(-) rename {img => _src/img}/github.svg (100%) rename {img => _src/img}/rustdoc.svg (100%) diff --git a/_src/README.md b/_src/README.md index b8f3d833..05eb7c4b 100644 --- a/_src/README.md +++ b/_src/README.md @@ -1,16 +1,9 @@ - [![GitHub]][repo] - [![rustdoc]][docs] - [![Latest Version]][crates.io] + GitHub + rustdoc + Latest Version -[GitHub]: /img/github.svg -[repo]: https://github.com/serde-rs/serde -[rustdoc]: /img/rustdoc.svg -[docs]: https://docs.serde.rs/serde/ -[Latest Version]: https://img.shields.io/crates/v/serde.svg?style=social -[crates.io]: https://crates.io/crates/serde -
# Serde diff --git a/_src/derive.md b/_src/derive.md index f1173c17..370e4834 100644 --- a/_src/derive.md +++ b/_src/derive.md @@ -16,15 +16,14 @@ bounds. On rare occasions, for an especially convoluted type you may need to These derives require a Rust compiler version 1.31 or newer. -!CHECKLIST -- Add `serde = { version = "1.0", features = ["derive"] }` as a dependency in +- [ ] Add `serde = { version = "1.0", features = ["derive"] }` as a dependency in Cargo.toml. -- Ensure that all other Serde-based dependencies (for example serde_json) are on +- [ ] Ensure that all other Serde-based dependencies (for example serde_json) are on a version that is compatible with serde 1.0. -- On structs and enums that you want to serialize, import the derive macro as +- [ ] On structs and enums that you want to serialize, import the derive macro as `use serde::Serialize;` within the same module and write `#[derive(Serialize)]` on the struct or enum. -- Similarly import `use serde::Deserialize;` and write `#[derive(Deserialize)]` +- [ ] Similarly import `use serde::Deserialize;` and write `#[derive(Deserialize)]` on structs and enums that you want to deserialize. Here is the `Cargo.toml`: diff --git a/img/github.svg b/_src/img/github.svg similarity index 100% rename from img/github.svg rename to _src/img/github.svg diff --git a/img/rustdoc.svg b/_src/img/rustdoc.svg similarity index 100% rename from img/rustdoc.svg rename to _src/img/rustdoc.svg From 325600e228928f4369c5414f08e1abd5f48a673a Mon Sep 17 00:00:00 2001 From: Noritada Kobayashi Date: Sat, 25 Jun 2022 18:44:44 +0900 Subject: [PATCH 4/4] Switch to mdBook (step 4) This commit works around an issue that mdBook does not have an alternative to the `!FILENAME` notation. --- _src/conventions.md | 2 +- _src/derive.md | 4 ++-- _src/error-handling.md | 2 +- _src/impl-deserializer.md | 2 +- _src/impl-serializer.md | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/_src/conventions.md b/_src/conventions.md index 3a678366..8d026e7c 100644 --- a/_src/conventions.md +++ b/_src/conventions.md @@ -26,7 +26,7 @@ pluggable pretty-printer trait as [`serde_json::ser::Formatter`]. A basic data format begins like this. The three modules are discussed in more detail on the following pages. -!FILENAME src/lib.rs +**src/lib.rs** ```rust # macro_rules! modules { # (mod de) => { diff --git a/_src/derive.md b/_src/derive.md index 370e4834..e0f6bf64 100644 --- a/_src/derive.md +++ b/_src/derive.md @@ -28,7 +28,7 @@ These derives require a Rust compiler version 1.31 or newer. Here is the `Cargo.toml`: -!FILENAME Cargo.toml +**Cargo.toml** ```toml [package] name = "my-crate" @@ -44,7 +44,7 @@ serde_json = "1.0" Now the `src/main.rs` which uses Serde's custom derives: -!FILENAME src/main.rs +**src/main.rs** ```rust use serde::{Serialize, Deserialize}; diff --git a/_src/error-handling.md b/_src/error-handling.md index 42f4fdab..f0e1706a 100644 --- a/_src/error-handling.md +++ b/_src/error-handling.md @@ -34,7 +34,7 @@ for its error type for the data structure to use in various situations. [`ser::Error`]: https://docs.serde.rs/serde/ser/trait.Error.html [data model]: data-model.md -!FILENAME src/error.rs +**src/error.rs** ```rust # macro_rules! ignore { # ($($tt:tt)*) => {} diff --git a/_src/impl-deserializer.md b/_src/impl-deserializer.md index 6901211d..dc65e2dd 100644 --- a/_src/impl-deserializer.md +++ b/_src/impl-deserializer.md @@ -30,7 +30,7 @@ there is no advantage to that. [Deserializer lifetimes]: lifetimes.md [Serde's data model]: data-model.md -!FILENAME src/de.rs +**src/de.rs** ```rust # mod error { # use std; diff --git a/_src/impl-serializer.md b/_src/impl-serializer.md index 96eb3040..86359461 100644 --- a/_src/impl-serializer.md +++ b/_src/impl-serializer.md @@ -14,7 +14,7 @@ is used. [`Serializer`]: https://docs.serde.rs/serde/trait.Serializer.html [Serde data model]: data-model.md -!FILENAME src/ser.rs +**src/ser.rs** ```rust # mod error { # pub use serde::de::value::Error;