search

executablebooks / cookiecutter-jupyter-book

Cookiecutter template for a simple jupyter book
https://executablebooks.github.io/cookiecutter-jupyter-book/
BSD 3-Clause "New" or "Revised" License
140 stars 53 forks source link

Makefile in template? #23

Open rowanc1 opened 3 years ago

rowanc1 commented 3 years ago

Wondering if including a Makefile might be a good idea? To me this is very helpful in onboarding to repositories as I can look to see what the commands are, and my previous relationships with sphinx always had Makefiles I believe?!

Even if they are small wrappers on the jupyter-book CLI make build/html/docs/serve

welcome[bot] commented 3 years ago

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

TomasBeuzen commented 3 years ago

Hi @rowanc1 - thanks for the comment! Could you expand more on what you'd like to see (based on your use cases). At least for me, the jupyter-book CLI takes care of mostly everything. My simple workflow is pretty much as follows:

  1. jupyter-book clean (clean files, not necessary but I like to start from a clean slate)
  2. jupyter-book build (this is really what I would have used make for in the past I suppose)
  3. A git push would trigger the online deployment for me (but that depends on having GH Actions set up and if you actually want to deploy online)

I usually speed up the build by caching executed notebooks.

But if others are using the CLI in a different way that would benefit from a Makefile I'd be interested to hear.

rowanc1 commented 3 years ago

The make file that I just created is below. :)

I completely agree that it is a bit redundant, my reflex, I suppose, is to reach for make commands over various CLIs because I move between a lot of projects and am forgetful.

The watch and serve commands below are nice to have when I am writing and I hit save, then the book rebuilds! Some of the integrations that I am building to jupyter-book also require the book to be run locally on a web server rather than off the file system.

.PHONY: build serve watch

build:
    jupyter-book build .

watch:
    nodemon -w './**' -e yml,md,ipynb --exec jupyter-book build .

serve:
    cd _build/html; python -m http.server 9000
TomasBeuzen commented 3 years ago

Awesome thanks! That's helpful (and interesting to know how you're using JB). I'm going to leave this issue open for a bit to see if there's any other interest :)