[RFC] How to deploy Nimibook ?

[Clonkk]

How to deploy Nimibook ?

Basically how to deal with 2 scenarios :

• I have existing documentation I want to migrate.
• I want to create a new book from scratch.

Some possible solutions :

• Create a new repo using the template feature of github. This requires creating a new repository "from scratch" and do not work outside of Github.
• Copy & Paste File. This means future evolution of the docs folders (js, fonts, FontAwesome, css) and the mustache files will have to be updated manually.
• Have a proc generateEmptyBook that copy latest docs folder and mustache files from latest Nimibook version. This requires to deploy docs and book with Nimble meaning we'll probably need to flatten the repository (or Nimble will complain) and the proc itself will probably differ between OS's (so added maintenance complexity ?).

So far, I don't see an "ideal" solution.

What do you think ?

[pietroppeter]

agree on scenarios and possible solutions. solution 3 I would say it can be generally stated as providing some automatic init and update mechanism for an nbook command (yet to come). that would be my ideal goal, but no concrete plan how to get there.

[pietroppeter]

while working on #18 I now have a better idea on how I would want to have the deploy mechanism and at the same time provides us with a cli.

• nimibook should be a package without a binary (and the cli I promised? see below)
• the first thing you do when you want to use it is nimble init as usual (add nimibook as a dependency)
• write a genbook (or renamed to nbook) nim file that contains:

import nimibook

nbBookTasks # or renamed to nimibookTasks or nimibookCli

• the templatenbBookTasks should implement the CLI for nimibook
• it should have a init task that will take copy the initial structure with all that is needed (the needed folders will need to be declared as kept in nimibook nimble)
• if you add a toc and some book configuration (e.g. title, description, ...) before calling the template, the init command /task will take that into account and create files accordingly mdbook does it too
• the init command can be run again, when a folder (say docs) it is already there it skips it. If you add stuff to toc that does not have a nim file, it will create it with already tha basic structure. there should be a mechanism to force the rewrite a specific folders, so that updating a nimibook is just a matter of updating the package and rerunning the init with the force mechanism (or maybe an update command that does the same).

Comment: the main idea behind this is that the library approach is again sufficient instead of having to provide a Cli. A Cli like mdbook needs to parse SUMMARY.md and book.toml but with the (ge)nbook.nim file you have already the toc and the book configuration already generated by a nice DSL; and the Cli is generated automatically by a single template invocation.

[HugoGranstrom]

I had never thought of this way before, but it seems to be the path of least resistance implementation-wise. And a strike of genius from your side 😄

if you add a toc and some book configuration (e.g. title, description, ...) before calling the template, the init command /task will take that into account and create files accordingly mdbook does it too

That there is a really convinient feature :)

there should be a mechanism to force the rewrite a specific folders, so that updating a nimibook is just a matter of updating the package and rerunning the init with the force mechanism (or maybe an update command that does the same).

Would the force rewrite delete docs/ and fetch an entirely new docs/ from the lastest version or is it more that we have a few files there which we replace? In other words, would the user be permitted to add persistent content in the docs/ folder or not?

[pietroppeter]

there should be a mechanism to force the rewrite a specific folders, so that updating a nimibook is just a matter of updating the package and rerunning the init with the force mechanism (or maybe an update command that does the same).

Would the force rewrite delete docs/ and fetch an entirely new docs/ from the lastest version or is it more that we have a few files there which we replace? In other words, would the user be permitted to add persistent content in the docs/ folder or not?

I think it should replace only the specific content that needs updating. If you add persistent content it should probably stay there.

[HugoGranstrom]

Ok that sounds like the most gentle way of doing it 👍

[Clonkk]

Close when #19 is merged