search

rougier / from-python-to-numpy

An open-access book on numpy vectorization techniques, Nicolas P. Rougier, 2017
http://www.labri.fr/perso/nrougier/from-python-to-numpy
Other
2.05k stars 340 forks source link

Add jupyter book version #104

Open lhoupert opened 3 years ago

lhoupert commented 3 years ago

As promised in https://github.com/rougier/from-python-to-numpy/issues/95 , I am proposing a jupyter-book version of the book. To generate the jupyter-book, I added a _config.yml and _toc.yml files. Then it is relatively straightforward to build the book.

Essentially:

  1. Install the most up to date version of jupyter-book:

    pip install git+https://github.com/executablebooks/jupyter-book

  2. Go to the root directory of the repository and run:

    jupyter-book build . --path-output jupyter-book/.

  3. Open Jupyter-book at jupyter-book/_build/html/index.html

Pdf version of the jupyter-book

It is also possible to use jupyter-book to generate a pdf version of the book, which could interest https://github.com/rougier/from-python-to-numpy/issues/99 . To do that you need to:

  1. Install pyppeteer

  2. Go to the root directory of the repository and run:

    jupyter-book build . --builder pdfhtml --path-output jupyter-book/.

  3. Open jupyter-book/_build/pdf/book.pdf

lhoupert commented 3 years ago

Deploying the book as an html website, is also relatively straightforward. I tested it on my website.

I first, created a new repository, then I copy the content of the _build/html directory and then I use the ghp-import package following instructions on the jupyter-book website (https://jupyterbook.org/start/publish.html).

The test repository I created can be seen here: https://github.com/lhoupert/test-jbook and the book can be seen online here: https://lhoupert.fr/test-jbook/book.html

rougier commented 3 years ago

Impressive! Many thanks. Maybe you can add your name in the preface with a new section About the Jupyer notebook and explaining you did the conversion for notebook and PDF.

Currently, the HTML displays some glitches (probably because of fonts) and movies are not rendered. Any idea?

Should I merge now and you'll open a new PR if needed or do you prefer I wait?

lhoupert commented 3 years ago

Hello @rougier , yes good idea. I will do that later this week and also try to see why the movies are not rendered. Do you have any example of glitches ?

rougier commented 3 years ago

In factn the only "glitch" is mostly the front page at https://lhoupert.fr/test-jbook/book.html. The copyright notice is too big compared to the title. By the way, you could also add your name/copyright on the front page for the ebook/jupyter conversion.

lhoupert commented 3 years ago

I fixed the gliches :-) For the video, I just copied again the data folder into the folder with the html/ build. I think the relative links were not recognized when inserting raw html block in the rst files?

Anyway I think it is good practice to have a self-contained html folder : it is easier to publish it using Github Pages tools.

A test version can be seen here: https://lhoupert.fr/test-jbook

lhoupert commented 3 years ago

@rougier if you want you could create a repository (e.g. from-python-to-numpy-jupyterbook? ) where you copied only the HTML folder from https://github.com/lhoupert/from-python-to-numpy/tree/add-jupyter-book-version/jupyter-book

If you follow the steps indicated here, you should be able to publish it on a custom domain name.

There is certainly a way to integrate this directly to this repository (from-python-to-numpy) using github CI/CD tools but I am less familiar with it.

Let me know what you think is the best. I am also happy to host it on my website, for example at lhoupert.fr/from-python-to-numpy-jupyter-book/