Use a Python CLI instead of Make

[choldgraf]

What do people think about using a Python CLI instead of a Makefile for simple commands? We could define the cli in scripts/ as a mini Python module called jupyter-book. Then, we could use Python to parse args and do stuff.

Right now, to build the book you run make book which calls python/generate_book.py.

Howeever, instead of this, we could instead tell people to first install the CLI with pip (e.g. pip install -e scripts/cli). Then they could run things like

# Generate the book
jupyter-book generate

# Clean the book
jupyter-book clean

# Serve the book
jupyter-book serve

What do folks think? The main reasons for this is that make is fairly annoying to use, and isn't always installed on people's machines, whereas we can probably more easily get people to install Python. Also Python has a much more powerful set of tools for parsing arguments and making a CLI.

Anyone have thoughts on this? Maybe @SamLau95 or @matthew-brett or @TomDonoghue ?

[matthew-brett]

Do you have an idea of the level of your users? I would have guessed that they would in general have to be at the level where they had no problem installing make.

It's much easier to add little one-liner targets, if its make.

Maybe fuse the two - put stuff into a CLI, and add tiny Make targets?

[choldgraf]

@matthew-brett that's a good point. I think that in general if we organize the python code to be used like a CLI (even if it's still called with make), it'll make things more modular and easier to test (e.g. that's how we now run the tests in scripts/tests.

[SamLau95]

I'm partial to make since it's a standard CLI tool used for many projects. For example, make clean and make build have fairly standardized meanings.

The downside as you mention is that make doesn't come pre-installed on Windows machines (I believe it's there for MacOS and most flavors of Linux). I think having a Python script do most of the heavy lifting while keeping a Makefile might be a good compromise.

[choldgraf]

yeah - that's basically where we are now. Sounds like folks generally agree that a thin layer of make on top of a python module is a good compromise

[choldgraf]

just a note that in #53 I added a mini python module in the scripts folder. Hopefully this will make it easier to add new functions etc in a more modular way rather than wrapping it all in one big script.

https://github.com/choldgraf/jupyter-book/tree/master/scripts/jupyterbook

It's a bit janky how we import stuff (basically the generate_book.py file manually adds the path to this module) but seems to get the job done for now. If folks have an idea for a better way to do this, feel free to mention it!

I'll leave this issue open since it's not quite a fix yet

[choldgraf]

now that the CLI is there, I think we can close this. There's still a small amount of make involved but it is much lighter, and easy to not use if we want to remove it in the future