Clonkk devel toc generation

[Clonkk]

This PR echo the discussion at #2
TODO : remove generated toc.mustache

[pietroppeter]

As mentioned, I like this approach (based on a simple Entry type).
I would still keep some of the design I introduced in #2 (below details) but I can easily do it in a follow PR. So if it is ok for you I can merge this and work from there. Ok?

details

The design I would keep from #2 (and would add on top of this) is:

1. a template based DSL, which would look like this:

let toc = newToc("books"):
  entry("Introduction", "index")
  entry("Basics", "basics/index"):
     entry("Plotting", basics/data_visualization")
  ...

2. a separate step to serialize toc as json while the rendering of the toc as template will be done in nbPostInit (with a final step to clean up the json). This is essential for the toc to be able to appear differently in every page. In particular it will be needed to support the is_active class (or for foldable content, see e.g. [Feature] expandable sidebar sections (ToC collapse) rust-lang/mdBook#1027)
3. the folder structure:
   • a src folder for the code to generate the toc and publishing the book. The idea is that in the future this repo could not only used as a template (copying and adjusting), but also as package, with a binary that can initialize structure.
   • a book folder for the content of the book (a specific reason you are using plural books? is it for symmetry with docs? if so I would argue that plural in docs is warranted since it will be a collection of documents, but I would go with singular book since it already implies a collection of content
   • a single genbook using the template dsl to state book structure and publish the book

[Clonkk]

a template based DSL, which would look like this:

Yeah, a template DSL is nice to have.

a separate step to serialize toc as json while the rendering of the toc as template

I'm not against JSON, but I'm not sure I understand how it is different from the mustache approach (I'm not well versed in web stuff). If you think it's necessary and/or easier moving forward, go ahead. Generating nested JSON from a seq[Entry] should be simple anyway.

the folder structure:

Repo being both a nimble package and a template was more or less the same thing in mind. books vs book is a minor details, there was no reason for me to use plural here (probably just habits of using plural for folders).

We'll also probably need to split procs and type definition into multiple files and rename some file, but this is polishing that can be done later.
I also like the nimble cleanbook stuff :)

but I can easily do it in a follow PR. So if it is ok for you I can merge this and work from there. Ok?

I think we can go ahead merging this as it fixed the API, and we'll improve the rest as we go along.

[pietroppeter]

I'm not against JSON, but I'm not sure I understand how it is different from the mustache approach (I'm not well versed in web stuff). If you think it's necessary and/or easier moving forward, go ahead. Generating nested JSON from a seq[Entry] should be simple anyway.

Well JSON is just used an on disk format to pass it from the genbook nim file to each of the pages. What I will use to serialize and deserialize is jsony which makes it effortless (and in the code we will only have a Toc object). The reason why not mustache is that the single entry will need to add is_active = true to a specific entry in the table and that is either done traversing the Toc object instead of working directly with the mustache.

It seems we agree on all the rest! 😄

[pietroppeter]

and thanks for this!