Source parser & generator for Rust Cookbook with mdBook

How to use

Put this crate inside rust-cookbook crate folder. Use cargo run inside this folder, before compiling cookbook with mdbook. Compile rust-cookbook.

Folder structure

data -> data folder
 
 category -> category folder (folder name -> category link)

 meta.json -> category meta 

  recipe -> recipe folder (folder name -> recipe link)

   content.md -> recipe content

   meta.json -> recipe metadata

Internals

• iterate through categories
• for each category iterate through recipes
• parse recipe metadata and content into rust struct
• collect all recipes and sort by "order" inside recipes metadata
• pass parsed data from parser.rs to generator.rs
• generate page title with category metadata
• generate table of contents using metadata of recipes
• generate recipes one by one with parsed recipe

Moving data

There are three ways to reorganize data in a new way:

1. change everything one by one and then include in build pros:

• we can do it one by one cons:
• we cannnot start using the system until everything is moved

2. change in chunks (whole categories) pros:

• we can start use it sooner cons:
• we cannot move everything in small chunks

3. add skipping option (skip categories and build other) pros:

• we can move data with small steps cons:
• needs to be implemented

Is reorganizing data difficult? Will it take lot of time?

I guess it would take few hours with one person, it is super easy. The problem may be with opened PRs cause they fix old files.

Should we reorganize data?

I think yes.

Cons:

• we need to put some effort into moving data into new format
• we need to maintain new tool

Pros:

• data easier to organize
• tables of contents automated

Is new tool complicated?

No. Its about 240 LOC and using regex, serde, serde_derive, serde_json. There is still some room for refactor.

Creating another repo for the tool

It may be more maintainable to use different repo for this tool but we would need some changes inside the code. It is a binary so may be installed with "cargo install".