Explore using a cookiecutter for the site

[choldgraf]

Currently, the instructions for Jupyter Book require somebody to copy the git repository or fork it. However, this causes a fair bit of confusion and may be problematic if people want to make multiple books.

Another option would be to define jupyter-book as a cookiecutter package that people can quickly populate with their project-specific info. I'm thinking something like:

1. The config.yml file can be populated with cookiecutter inputs
2. There's another cookiecutter input for a path to a folder that contains the book's content. It will then copy that folder into the content/ folder.
3. An option to automatically generate a YAML file with the TOC using the alphanumeric ordering of the content folder. Then users can edit that as they wish to get it right.

This way, you should be able to get up-and-running with jupyter-book more easily, and it might making upgrading easier in the future.

Design spec

From the user's perspective

A CLI is used to manage the creation of new Jupyter Books. Something like

jupyter-book create
  [--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

Jupyter-book will then use the cookiecutter python moule to create a new jupyter book project from the template. It will do the following:

1. Create a new project template, pre-filling any fields that are specified in config.yaml and asking questions for the remaining fields using cookiecutter
2. If --content is provided, copy the notebooks in --content to the content/ folder of the resulting repository
3. If --toc is provided, copy the file to the _data/toc.yml file. If --content is provided but not --toc is provided, auto-populate a TOC using alphanumeric ordering of the content folder to help people get started.
4. Choose a license using a hook that is configured with the config.yaml file

In this way, users could upgrade to a new version of jupyter book by keeping their book's configuration file separate along w/ the TOC and then running

jupyter-book create --version <new-version> --config path/to/bookconfig.yml --content path/to/mycontent.yaml --toc path/to/mytoc.yml

The result should be a fully-functioning book that can be run with make book, w/ the latest CSS/JS/etc in the jupyter-book repository.

I know that @arokem likes cookiecutters. Do you think this sounds reasonable? I saw that @gnestor was also commenting in the cookiecutter repo, any chance you have thoughts? :-)

[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]

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!

[choldgraf]

see #89

[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! 👍

[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!