This is a squashed commit. It roughly encompasses the following changes.
---
\# Book
- Created another private submodule, mdbook::loader::book
- This submodule contains the data types representing a Book
- For now the Book just contains a list of BookItems (either chapters or
separators)
- A Chapter contains its name, contents (as one long string), an
optional section number (only numbered chapters have numbers,
obviously), and any nested chapters
- There's a function for loading a single Chapter from disk using it's
associated Link entry from the SUMMARY.md
- Another function builds up the Book by recursively visiting all Links
and separators in the Summary and joining them into a single
Vec<SummaryItem>. This is the only non-dumb-data-type item which is
actually exported from the book module
\# Loader
- Made the loader use the book::load_book_from_disk function for
loading a book in the loader's directory.
\# Tests
- Made sure you can load from disk by writing some files to a temporary
directory
- Made sure the Loader can load the entire example-book from disk and
doesn't crash or hit an error
- Increased test coverage from 34.4% to 47.7% (as reported by cargo
kcov)
From the [pull request comment][pr], here's a rough summary of what
was done in the squashed commits.
---
\# Summary Parser
- Added a private submodule called `mdbook::loader::summary` which
contains all the code for parsing `SUMMARY.md`
- A `Summary` contains a title (optional), then some prefix, numbered,
and suffix chapters (technically `Vec<SummaryItem>`)
- A `SummaryItem` is either a `Link` (i.e. link to a chapter), or a
separator
- A `Link` contains the chapter name, its location relative to the
book's `src/` directory, and a list of nested `SummaryItems`
- The `SummaryParser` (a state machine-based parser) uses
`pulldown_cmark` to turn the `SUMMARY.md` string into a stream of
`Events`, it then iterates over those events changing its behaviour
depending on the current state,
- The states are `Start`, `PrefixChapters`, `NestedChapters(u32)` (the
`u32` represents your nesting level, because lists can contain lists),
`SuffixChapters`, and `End`
- Each state will read the appropriate link and build up the
`Summary`, skipping any events which aren't a link, horizontal rule
(separator), or a list
\# Loader
- Created a basic loader which can be used to load the `SUMMARY.md` in
a directory.
\# Tests
- Added a couple unit tests for each state in the parser's state
machine
- Added integration tests for parsing a dummy SUMMARY.md then asserting
the result is exactly what we expected
[pr]: https://github.com/azerupi/mdBook/pull/371#issuecomment-312636102
Move non-test test module files into their own directories to prevent
cargo from running them as tests. Then suppress the left-over warnings.
Move *dummy book* code and data into a shared folder, and leave the rest
of helper utilities (one function) in the original module.
`HtmlConfig` was both guaranteed to exist within `BookConfig`
and `expect`ed in few places.
This simplifies the API a little by representing the fact that
`HtmlConfig` is currently mandatory for proper mdBook binary operation.
- removing need to explicitly use `Path::new` all over the place
- removed warnings from doctests (normally invisible unless `cargo test -- --nocapture`)
- no doctests are norun/ignore now
- updated docs both in book-example and in docs not to refer to nonexisting API's
Michael Bryan
Behnam Esfahbod
projektir
Michal Budzynski
Mathieu David
Jimmy Do