Explore using a cookiecutter for the site

[executablebooks]

Explore using a cookiecutter for the site

[arokem]

Yes. I think that would be an improvement. I just found myself a few days ago trying to start one of these again and being confused about what I am supposed to do (e.g., which files are optional and which ones are required).

[choldgraf]

see #89

[choldgraf]

@gnestor well I think we are one step ahead of you :-) there's a PR that implements a jupyter-book CLI here: #89 would love to hear what you think about it!

[choldgraf]

this is now done with the CLI!

[choldgraf]

cc @yuvipanda who I think has a good eye for user-interface design! do you have any thoughts on the above?

[choldgraf]

hmmm, I'm a bit worried that cookiecutter won't work here, this is primarily because cookiecutter uses liquid templates, which also use the {{ convention used throughout this site. This means that we'd have to wrap all of our {{ in raw tags, or double-escape them ({{ {{ site.xxx }} }}), see cookiecutter/cookiecutter#9

That seems like enough addition of complexity that cookiecutter isn't quite worth it. Moreover it seems that patches to cookiecutter will take a looong time to get merged, as the author(s) don't seem super invested in it in terms of time. :-/

Another option

Keep the book in a template-like form but a bit more light-weight than what cookiecutter uses. Split out the jupyter-book repo into two folders:

• book_template/ would have a template book repository very similar to what is here now.
• cli/ would have a little python package that controls jupyter-book.

You'd create a new jupyter book using a pattern like:

jupyter-book create
  --name mybook  # The name of the book to be created (also the output folder)
  [--version v0.1]  # Specifies a version of jupyter-book
  [--config myconfig.yaml]  # Pre-fill these configuration options
  [--content path/to/content/folder]  # Folder w/ Jupyter Notebooks + markdown files
  [--toc path/to/toc.yml]  # With URLs relative to the content folder
  [--css path/to/custom.css]  # Custom CSS rules to add to the site
  [--js path/to/script.js]  # Custom JS scripts to add to the site

In this case, we'd use ruamel to let the user give their own YAML configuration. This would simply update the fields that are in _config.yaml in the book_template/ folder. In this way there wouldn't be any live user-input, it'd only be a question of updating whatever fields are there.

[yuvipanda]

@choldgraf said this to me in person yesterday and I like it!

[arokem]

I like this too. I think that a CLI would be good. You might even make it ask questions (doesn't cookiecutter do that?), instead of having to enter in command-line arguments. WDYT?

…

On Wed, Jan 23, 2019 at 11:32 AM Yuvi Panda ***@***.***> wrote: @choldgraf <https://github.com/choldgraf> said this to me in person yesterday and I like it! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#87 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAHPNjggjFK8gxYIGh-9yu2OpCPAdt_3ks5vGLiygaJpZM4aJbq2> .

[choldgraf]

cool, will prototype something soon!

[gnestor]

Sorry for the delay! I was reading and thinking that this sounds like it would need its own CLI. AFAIK cookiecutters don't allow for arbitrary scripts to be run in response to inputs, so copying files from a contents folder into the project can't be accomplished by cookiecutters alone. You can get creative and inject paths into a python or bash script in the template and run that script as apart of setup.py or something. I'm glad that you arrived at a similar conclusion for completely different reasons! 👍