From 800fb54aeb2ed5132d584de635c377b951cc8133 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 22 Aug 2025 17:13:27 -0700 Subject: [PATCH] Rename Book.sections to Book.items This renames the "sections" list to "items". In practice, this list has contained more than just "sections" since parts were added. Also, the rest of the code consistently uses the term "items", since the values it contains are called `BookItem`s. Finally, the naming has always been a little confusing to me. This is a very disruptive change, and I'm not doing it lightly. However, since there are a number of other API changes going into 0.5, I think now is an ok time to change this. --- crates/mdbook-core/src/book.rs | 18 +++++++++--------- crates/mdbook-core/src/book/tests.rs | 2 +- crates/mdbook-driver/src/load.rs | 4 ++-- .../mdbook-html/src/html_handlebars/search.rs | 2 +- crates/mdbook-summary/src/lib.rs | 6 +++--- examples/nop-preprocessor.rs | 2 +- guide/src/for_developers/preprocessors.md | 2 +- tests/testsuite/config.rs | 2 +- tests/testsuite/preprocessor.rs | 2 +- tests/testsuite/renderer.rs | 2 +- tests/testsuite/search.rs | 2 +- 11 files changed, 22 insertions(+), 22 deletions(-) diff --git a/crates/mdbook-core/src/book.rs b/crates/mdbook-core/src/book.rs index 424c19c4be..e542c8e375 100644 --- a/crates/mdbook-core/src/book.rs +++ b/crates/mdbook-core/src/book.rs @@ -11,9 +11,9 @@ mod tests; /// A tree structure representing a book. /// -/// For the moment a book is just a collection of [`BookItems`] which are -/// accessible by either iterating (immutably) over the book with [`iter()`], or -/// recursively applying a closure to each section to mutate the chapters, using +/// A book is just a collection of [`BookItems`] which are accessible by +/// either iterating (immutably) over the book with [`iter()`], or recursively +/// applying a closure to each item to mutate the chapters, using /// [`for_each_mut()`]. /// /// [`iter()`]: #method.iter @@ -21,8 +21,8 @@ mod tests; #[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)] #[non_exhaustive] pub struct Book { - /// The sections in this book. - pub sections: Vec, + /// The items in this book. + pub items: Vec, } impl Book { @@ -33,13 +33,13 @@ impl Book { /// Creates a new book with the given items. pub fn new_with_items(items: Vec) -> Book { - Book { sections: items } + Book { items } } /// Get a depth-first iterator over the items in the book. pub fn iter(&self) -> BookItems<'_> { BookItems { - items: self.sections.iter().collect(), + items: self.items.iter().collect(), } } @@ -55,12 +55,12 @@ impl Book { where F: FnMut(&mut BookItem), { - for_each_mut(&mut func, &mut self.sections); + for_each_mut(&mut func, &mut self.items); } /// Append a `BookItem` to the `Book`. pub fn push_item>(&mut self, item: I) -> &mut Self { - self.sections.push(item.into()); + self.items.push(item.into()); self } } diff --git a/crates/mdbook-core/src/book/tests.rs b/crates/mdbook-core/src/book/tests.rs index c49dac80d8..54cb005bbd 100644 --- a/crates/mdbook-core/src/book/tests.rs +++ b/crates/mdbook-core/src/book/tests.rs @@ -26,7 +26,7 @@ fn book_iter_iterates_over_sequential_items() { ]; let book = Book::new_with_items(items); - let should_be: Vec<_> = book.sections.iter().collect(); + let should_be: Vec<_> = book.items.iter().collect(); let got: Vec<_> = book.iter().collect(); diff --git a/crates/mdbook-driver/src/load.rs b/crates/mdbook-driver/src/load.rs index 2c97069636..401f08fcc9 100644 --- a/crates/mdbook-driver/src/load.rs +++ b/crates/mdbook-driver/src/load.rs @@ -284,8 +284,8 @@ And here is some \ PathBuf::from("chapter_1.md"), vec![], ); - let sections = vec![BookItem::Chapter(chapter)]; - let should_be = Book::new_with_items(sections); + let items = vec![BookItem::Chapter(chapter)]; + let should_be = Book::new_with_items(items); let got = load_book_from_disk(&summary, temp.path()).unwrap(); diff --git a/crates/mdbook-html/src/html_handlebars/search.rs b/crates/mdbook-html/src/html_handlebars/search.rs index 1a235208f6..a424f80132 100644 --- a/crates/mdbook-html/src/html_handlebars/search.rs +++ b/crates/mdbook-html/src/html_handlebars/search.rs @@ -38,7 +38,7 @@ pub(super) fn create_files( .add_field_with_tokenizer("breadcrumbs", Box::new(&tokenize)) .build(); - let mut doc_urls = Vec::with_capacity(book.sections.len()); + let mut doc_urls = Vec::with_capacity(book.items.len()); let chapter_configs = sort_search_config(&search_config.chapter); validate_chapter_config(&chapter_configs, book)?; diff --git a/crates/mdbook-summary/src/lib.rs b/crates/mdbook-summary/src/lib.rs index 24a4bc61e1..2039a63e9b 100644 --- a/crates/mdbook-summary/src/lib.rs +++ b/crates/mdbook-summary/src/lib.rs @@ -601,9 +601,9 @@ impl<'a> SummaryParser<'a> { } } -fn update_section_numbers(sections: &mut [SummaryItem], level: usize, by: u32) { - for section in sections { - if let SummaryItem::Link(ref mut link) = *section { +fn update_section_numbers(items: &mut [SummaryItem], level: usize, by: u32) { + for item in items { + if let SummaryItem::Link(ref mut link) = *item { if let Some(ref mut number) = link.number { number[level] += by; } diff --git a/examples/nop-preprocessor.rs b/examples/nop-preprocessor.rs index 488271dc90..7327dcfb1a 100644 --- a/examples/nop-preprocessor.rs +++ b/examples/nop-preprocessor.rs @@ -134,7 +134,7 @@ mod nop_lib { "mdbook_version": "0.4.21" }, { - "sections": [ + "items": [ { "Chapter": { "name": "Chapter 1", diff --git a/guide/src/for_developers/preprocessors.md b/guide/src/for_developers/preprocessors.md index 1ffc708ed1..48c27fa373 100644 --- a/guide/src/for_developers/preprocessors.md +++ b/guide/src/for_developers/preprocessors.md @@ -91,7 +91,7 @@ if __name__ == '__main__': # load both the context and the book representations from stdin context, book = json.load(sys.stdin) # and now, we can just modify the content of the first chapter - book['sections'][0]['Chapter']['content'] = '# Hello' + book['items'][0]['Chapter']['content'] = '# Hello' # we are done with the book's modification, we can just print it to stdout, print(json.dumps(book)) ``` diff --git a/tests/testsuite/config.rs b/tests/testsuite/config.rs index 59d962b4b1..df0a3013b1 100644 --- a/tests/testsuite/config.rs +++ b/tests/testsuite/config.rs @@ -54,7 +54,7 @@ fn preprocessor_cfg_from_env() { let mut s = String::new(); std::io::stdin().read_to_string(&mut s).unwrap(); std::fs::write("out.txt", s).unwrap(); - println!("{{\"sections\": []}}"); + println!("{{\"items\": []}}"); } "#, ) diff --git a/tests/testsuite/preprocessor.rs b/tests/testsuite/preprocessor.rs index de3e5efe38..dab2f88d33 100644 --- a/tests/testsuite/preprocessor.rs +++ b/tests/testsuite/preprocessor.rs @@ -115,7 +115,7 @@ fn relative_command_path() { let mut s = String::new(); std::io::stdin().read_to_string(&mut s).unwrap(); std::fs::write("preprocessor-ran", "test").unwrap(); - println!("{{\"sections\": []}}"); + println!("{{\"items\": []}}"); } "#, ) diff --git a/tests/testsuite/renderer.rs b/tests/testsuite/renderer.rs index 456fcd7e56..b8070c5c9d 100644 --- a/tests/testsuite/renderer.rs +++ b/tests/testsuite/renderer.rs @@ -167,7 +167,7 @@ fn backends_receive_render_context_via_stdin() { str![[r##" { "book": { - "sections": [ + "items": [ { "Chapter": { "content": "# Chapter 1\n", diff --git a/tests/testsuite/search.rs b/tests/testsuite/search.rs index c0f8fb2ebd..937133f37f 100644 --- a/tests/testsuite/search.rs +++ b/tests/testsuite/search.rs @@ -117,7 +117,7 @@ fn with_no_source_path() { let test = BookTest::from_dir("search/reasonable_search_index"); let mut book = test.load_book(); let chapter = Chapter::new("Sample chapter", String::new(), "sample.html", vec![]); - book.book.sections.push(BookItem::Chapter(chapter)); + book.book.items.push(BookItem::Chapter(chapter)); book.build().unwrap(); }