diff --git a/doc/assets/bookdata.graphml b/doc/assets/bookdata.graphml index e60ad73c..a1722780 100644 --- a/doc/assets/bookdata.graphml +++ b/doc/assets/bookdata.graphml @@ -121,15 +121,15 @@ chapters - + - BookConfig - root -src -dest -template -renderer + BookConfig + lang +project_root +book_dest +book_src +template_path @@ -145,12 +145,13 @@ renderer - + Book - metadata -chapters + config +metadata +toc @@ -170,7 +171,7 @@ chapters Renderer - render(book, config) + render(book) @@ -186,12 +187,13 @@ chapters - + - MDBook - books -config + MDBook + project_root +books +renderer @@ -223,7 +225,7 @@ config - + BookMetadata @@ -245,13 +247,12 @@ publisher - + Vec<Chapter> - title -file -sub_chapters + title +file @@ -281,6 +282,48 @@ sub_chapters + + + + + + + + + summary +parser + + + + + + + + + + + + + + + + + + Vec<TocItem> + content +sub_items + + + + + + + + + + + + @@ -296,29 +339,29 @@ sub_chapters - - + + - behaviour control, + behaviour control, paths, target format - + - - + + - paths + paths - + @@ -326,11 +369,11 @@ paths, target format - + - metadata + metadata @@ -338,68 +381,56 @@ paths, target format - + - + - + - chapter list + chapter list - + - + - + - chapter attributes + chapter attributes chapter content - + - + - + - + - + - - - - - - - - - - - - - + @@ -407,15 +438,27 @@ chapter content - + - + - + + + + + + + + + + + + + @@ -431,55 +474,19 @@ chapter content - + - - + + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + @@ -494,7 +501,7 @@ data - + @@ -506,7 +513,7 @@ data - + @@ -516,7 +523,7 @@ data - + @@ -526,6 +533,80 @@ data + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/assets/bookdata.png b/doc/assets/bookdata.png index bcab50dc..f206399a 100644 Binary files a/doc/assets/bookdata.png and b/doc/assets/bookdata.png differ diff --git a/doc/assets/structs-reorganized.png b/doc/assets/structs-reorganized.png new file mode 100644 index 00000000..cd33bb9c Binary files /dev/null and b/doc/assets/structs-reorganized.png differ diff --git a/doc/assets/structs-reorganized.pum b/doc/assets/structs-reorganized.pum new file mode 100644 index 00000000..6dc4de93 --- /dev/null +++ b/doc/assets/structs-reorganized.pum @@ -0,0 +1,129 @@ +@startuml + +class book::MDBook { + project_root : PathBuf + + books : HashMap<&'a str, Book> + + renderer : Box + livereload : Option + indent_spaces: i32 + multilingual: bool + + new(root) +} + +class book::book.Book { + config : BookConfig + metadata : BookMetadata + + chapters: Vec + + new(title) +} + +class book::bookconfig.BookConfig { + lang : Language + + project_root : PathBuf + book_dest : PathBuf + book_src : PathBuf + template_path : PathBuf + + new(root) +} + +class book::chapter.Chapter { +title +file +author +description +css_class +index : Vec + +new(title, file) +} + +namespace book::toc { + +class TocItem { + content : TocContent + sub_items: Vec + new(content) +} + +enum TocContent { + Frontmatter "Chapter" + Mainmatter "Chapter" + Backmatter "Chapter" + Insert "Chapter" + Spacer +} + +} + +namespace book::metadata { + +class BookMetadata { + title + subtitle + description + publisher + language + authors + translators + number_format + section_names + new(title) +} + +class Author { + name + email + new(name) +} + +class Language { + name + code +} + +class Publisher { + name + url + logo_src +} + +enum NumberFormat { + Arabic + Roman + Word +} + +} + +class renderer::html_handlebars::HtmlHandlebars { + new() + render(book: MDBook) +} + +class theme::Theme { + index + css + favicon + js + highlight_css + tomorrow_night_css + highlight_js + jquery + new(src) +} + +book::book-[hidden]->book::bookconfig +book::book-[hidden]->book::chapter +book::book-[hidden]->book::toc +book::book-[hidden]->book::metadata + +renderer::html_handlebars::HtmlHandlebars-[hidden]->theme::Theme + +@enduml diff --git a/doc/doc.md b/doc/doc.md index 27ae47a5..961f4926 100644 --- a/doc/doc.md +++ b/doc/doc.md @@ -1,17 +1,38 @@ # Doc -Diagrams are with [yEd](http://www.yworks.com/products/yed) and [plantuml](http://plantuml.com). +Diagrams are with [yEd](http://www.yworks.com/products/yed) +and [plantuml](http://plantuml.com). ## Data +`MDBook::new(root)` parses CLI args and `book.toml` to create: + +- app config settings +- `Book` for each language + +Each `Book` is given their config setting with their source- and destination +paths. + +The renderer can then render each book. + +To render the TOC, renderer gets a Vec from summary parser. + +The renderer walks through the Vec. It can match content kinds in an enum and +this way knows whether to render: + +- front- back- or mainmatter +- spacer elements (vertical space in TOC but no chapter output) +- insert chapters (no TOC link, but the chapter is part of the reading sequence) + ![book data](assets/bookdata.png) ### Renderer -Takes data from: +Takes a book, which knows: -- a book's metadata and chapters (`Book`) -- paths and behaviour config (`BookConfig`) +- metadata +- toc with chapters +- config for paths - template assets (`template_path`) For generating pages: @@ -22,7 +43,8 @@ those properties which can be easily anticipated. If Renderer needs more specific data, it can be supplied in `book.toml`. It's the Renderer's job to open that and parse it out. -Chapters, `Vec`. +Chapters are represented in a `Vec`, each item has the chapter content +as payload. If the user wants to store attributes that are not anticipated with structs, they can go in a hashmap with string keys, let them be accessible from the @@ -41,26 +63,20 @@ renderer. Takes data from: - CLI args -- book.json +- book.toml ## Structs +### Reorganized + +![structs reorganized](assets/structs-reorganized.png) + ### Currently -Already almost good for implementing the above. - -Storing data attributes can be reorganized. - -Modules could be refactored to express intention more clearly. - ![structs](assets/structs.png) ## Notes -There could be less modules. Merge modules which express one intention. - -The two Chapter structs could be refactored out. - Take config paths for as many things as possible. Let the user organize their project folder differently, or allow `mdbook` to function in existing projects with already established folders.