[RFC] nimibook cli design proposal

[pietroppeter]

The following is my design idea for a cli-generating template nimibookCli that will allow to support deploy mechanism (see discussions in #12, #19).

nbook.nim

main file for managing a nimibook project should be a nbook.nim (renamed genbook since it will do more) with the following structure:

import nimibook

var book = newBookFromToc("My book", "book"):
  entry("Introduction", "index")
  # other entries
  
book.git_repository_url = # ...
# other book configurations

nimibookCli # a template provided by nimibook library

Note that the cli should be a real cli and not based on compile time switches as currently is. This means in particular that unless the toc or book configuration change, there is no need to recompile.

The user starting from an empty repository and adding a file with the above content, should be able to call the following commands with the generated cli (after calling nim c nbook or calling directly nim r nbook <command>).

nbook init

On first call it will create the initial folder structure:

.
├── book              # source of the book
│      ├── index.nim  # basic structure for nimibook nim file
│      └── ...        # other nimibook documents and folders needed for the toc
├── docs              # build location for the book
│      └── assets     # css, js, fonts, ...
├── templates         # mustache templates
├── nbook.nim         # source for toc, book configuration and cli
├── .gitignore
├── config.nims
└── README.md

Inside book folder it will create appropriate nim and md files reflecting current toc.
On subsequent call it will not overwrite existing files. So if init is already called once it will likely only add new files if they have been added to the toc. If you provide a folder or file it will restrict the init operation to that specific folder or file.

nbook check

It will check that current folder structure reflects book toc, configuration (and the internal nimibook assets). It will also lists any other files that are not reflected in current structure.
You should be able to provide a path (folder or file) and the check operation should be restricted to that folder or file.

nbook clean

It will remove all files that should not be represented by current structure. It will also remove outputs of build process (e.g. book.json and html files). It should have a mechanism to protect specific files or folders (some api that you put in nimibook? something like book.keep = @["somefolder", "some/file.nim", ...]). You should be able to provide a path (folder or file) and the clean operation should be restricted to that folder (or file).

nbook build

It will build the book output starting from the toc and generating all files. If you provide a folder or a file it will restrict the build operation only to that folder or file.

nbook update

Same as init but it will overwrite the content instead of doing nothing in the case that a file exists.

[HugoGranstrom]

Certainly an interesting proposal, letting the user themselves build the CLI binary on a per-project basis solves a lot of problems :D

I do feel like the nim r nbook.nim <command> has some advantages over the binary approach though. But mainly for non-deploying like updating the toc and forgetting to recompiling the binary. But in deployment, it would probably be compiled anew every time either way so it wouldn't matter which of them was used. The same argument can be had for updating versions of nimiBook itself as one could forget to recompile.

[Clonkk]

This seem reasonable.
Do you eventually consider book.json as input for the table of content or is toc input based on DSL the plan ? (I asked because multiplexing input types could be more complex).

[pietroppeter]

Do you eventually consider book.json as input for the table of content or is toc input based on DSL the plan ?

no, never considered book.json as input for DSL, just a convienent way to pass around information from driver program to single document.

[Clonkk]

it will remove all files that should not be represented by current structure. It will also remove outputs of build process (e.g. book.json and html files). It should have a mechanism to protect specific files or folders (some api that you put in nimibook? something like book.keep = @["somefolder", "some/file.nim", ...]). You should be able to provide a path (folder or file) and the clean operation should be restricted to that folder (or file).

Regarding clean, I also ignore files in *.nims, .git*, *.cfg in book. They are technically not part of the tree, but I think we want to keep those.

#19 Does most of what you specified but without the ability to provide a path for now (but that shouldn't too hard to add with parseOpt)

[pietroppeter]

closing this and tracking lack of path here: #27