Improve docs for 0.3 (fix #51) + changelog + make it nim v2.0 compatible

[pietroppeter]

improve documentation

• improve readme
  • add mention of js interactivity
  • current status
  • example sites
  • features
  • minimal howto use (shows nbook init and nbook build)
  • review contribute
  • remove tips and tricks (all content is in docs)
• improve book
  • change toc structure
  • chapter content: nim default template or markdown
    • add latex here and remove latex chapter
  • chapter toc: explain better the toc dsl
  • chapter configuration: list all configuration options
  • chapter cli: explain better the cli
    • how to customize compile flags
    • how to build a single file (use dump)
    • parallel builds and how to switch them off (and how to set max parallel builds)
  • remove chapter tasks (not interesting for the user)

additional improvements of this PR:

• improve nbook cli help (document dump and build options)
• changed behaviours of clean and update commands
• less logging (no config and toc every time you use nbook)
• remove the rust file
• add as vendored the assets (css, font and js stuff)
• remove toml serialization dependency (make it nim 2.0 ready)
• add nim devel and stable to CI

created changelog complete with history of 0.1 and 0.2 + updates on 0.3:

• add latex support with latex as in nimib (PR add latex support with katex #52)
• recent parallel build by beef
• fixes to parallel build by Hugo (Fix async and some other stuff #61)
• document changes in update nimibook to 0.3 + much needed maintenance WIP #50
  • refactoring and code structure (review)
  • templates
  • book.json
  • blocks context in document.mustache
  • cfg stuff
    • note that changes also fix Use different "book" directory #48 (you should be able to change name of book folder)
  • remove default parameters and allow to pass parameters to build
  • improved init
  • new nb/doc object in Book
    • refactored Book.book_title into Book.title. Overrides previously existing Book.title which was supposed to be used for the Chapter title
    • removed book.path_to_root (it is a document/chapter thing)
  • remove rootfolder in toc and path field in Toc
• after nimib 0.3 is released, change nimib dep

create (or link) issues for other improvements to do in next versions:

• add nim code highlighting when starting from md file highlight nim code in pages with markdown sources #64
• support part title in toc part title: section without a reference page #45
• support SUMMARY.md support SUMMARY.md for table of contents #62
• nbook binary provide a nbook/nimibook binary #63
• improve clean improve clean command #66
• dumped book.json (now a public api) should not contain cfgDir and it should only contain relative dirs book.json should only contain relative dirs #67
• quit failures for check and build should be only in cli refactor check to return number of failures #68

edit: this first PR message was multiple times edited (in particular adding todo points from #51)
to keep it up to date with PR content. The discussion below might reflect an earlier version of this ,message.

[HugoGranstrom]

Seems like you are using the NETLIFY_SITE_ID from your nimib project instead of the nimibook one

[pietroppeter]

Seems like you are using the NETLIFY_SITE_ID from your nimib project instead of the nimibook one

damn you are good! I was trying indeed to understand what went wrong! I should have fixed it now, let's see.

[pietroppeter]

not sure why this is still hanging here, my bad, will try to look a this. also #51 has a bunch of tasks I listed back then and not sure if they are covered by this (which is essentially just adding a changelog and making sure we use nimib 0.3 - which is now probably outdated already - we should use latest stable...

[HugoGranstrom]

Yes it would be nice if we could get nimibook 0.3 released soon, so we can focus fully on the SSG + nimib org in the coming months. I will try and get pietroppeter/nimib#163 done this week, so we can merge #61 as soon as possible as well. Is there anything else code-wise that has to be done, or was stabilizing the parallel build the final thing?

[pietroppeter]

No, I do not recall anything code wise that needed to be done. It was mostly documenting all the changes the went through the refactoring. For the async thing at the time the idea was to disable, now there is no need to do it.

[pietroppeter]

Does #61 depends on that nimib code thing?

[HugoGranstrom]

Ok, that's good 👌

[HugoGranstrom]

I added the parallel out.js fix to that PR 🙃 could have done it in a separate PR of course... But I just have to go through all the existing nimib documents again and confirm nothing has been broken by it. (When you have to read through all of scinim/getting-started you realize that we have quite a bit of material there 🤣)

[pietroppeter]

added the parallel out.js fix to that PR

ah ok right, you mentioned that

[HugoGranstrom]

If I don't find any bugs in it, I should be able to have it done tomorrow evening. And then I should have #61 done on saturday. Just in time before the speaking hours 😎

[pietroppeter]

wait the error in tests I see is due to the out.js and is the one that will be fixed?

[HugoGranstrom]

Yes I think so, it's hard to tell without seeing the log file though 😛 I think we are always compiling a js file even if no nbJs is used, but I fixed that one as well in the nimib PR. Hence the error here even if we don't use nbJs

[pietroppeter]

wait the error in tests I see is due to the out.js and is the one that will be fixed?

I see that if I run multiple times nimble genbook I occasionally get the same error I see in CI and it seems to be tied to out.js. Why are we producing a js since this book has no js functionalities?

[HugoGranstrom]

Because I never added a check to see if we actually wrote any nbJs code. So it just compiles an empty .nim file in this case for every file. As I said, I have fixed this as well in the nimib PR by checking if we have any code to compile.

[pietroppeter]

anyway now I remember what this PR was about, documentation on how to use nimibook needs to be improved substantially. things changed in last refactoring and they are not documented anywhere (except in the code)

[pietroppeter]

finally this PR is ready to be merged! @HugoGranstrom do you want to give a quick look before I merge and tag 0.3 release?

I did change substantially the documentation that now reflects the current state of nimibook.
Also the changelog is now rather complete.
And I have also made some additional improvements in this PR:

• added support for nim 2.0 by removing dependency on toml_serialization (used the useful loadTomlSection from nimib)
• changed behaviors of some commands (clean and update)

see first PR message for all the details (I kept it up to date).

[HugoGranstrom]

Awesome work on cleaning up and writing documentation! 😄

I didn't find anything major, just a few link-related comments that needs to be fixed and a very picky comment on the Latex part :)

[pietroppeter]

Thanks! Will wait for CI to finish and merge after giving another look at the preview.