Generate notebook with HTML for admonitions

[lesteve]

Fix #107.

This allows:

• to keep using admonitions with their nice output in JupyterBook
• to have some HTML to view these admonitions in a Jupyter notebook / JupyterLab interface

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[lesteve]

JupyterBook

https://inria.github.io/scikit-learn-mooc/python_scripts/02_numerical_pipeline_hands_on.html

Notebook

https://nbviewer.jupyter.org/github/inria/scikit-learn-mooc/blob/master/notebooks/02_numerical_pipeline_hands_on.ipynb

The HTML generation logic is in the admonition_html function with plenty of space for improvements.

[lesteve]

And just so that the hack is more explicit the markdown cell for the example above in the Jupyter notebook looks like this:

<div class="admonition tip alert alert-warning">
<p class="first admonition-title" style="font-weight: bold;">Tip</p>
<p class="last"><tt class="docutils literal">random_state</tt> parameter allows to get a deterministic results even if we
use some random process (i.e. data shuffling).</p>
</div>

In the previous notebook, we used a k-nearest neighbors predictor. While this
model is really intuitive to understand, it is not widely used. Here, we will
a predictive model belonging to the linear model families.

<div class="admonition note alert alert-info">
<p class="first admonition-title" style="font-weight: bold;">Note</p>
<p class="last">In short, these models find a set of weights to combine each column in the
data matrix to predict the target. For instance, the model can come up with
rules such as <tt class="docutils literal">0.1 * age + 3.3 * <span class="pre">education-num</span> - 15.1 &gt; 0</tt> means that
<tt class="docutils literal"><span class="pre">high-income</span></tt> is predicted.</p>
</div>

Thus, we will use a logistic regression classifier and train it.

[GaelVaroquaux]

Maybe a small docstring to explain what is going on in this file / what is its purpose

[lesteve]

Yeah that's a good point, I added small docstrings (be it only to remember it myself) to the functions but not to the module.

[lesteve]

Done in d61c5c1

[mgeier]

Just FYI: nbsphinx allows you to use <div> elements with alert-info and alert-warning transparently: https://nbsphinx.readthedocs.io/en/0.8.1/markdown-cells.html#Info/Warning-Boxes

[lesteve]

Thanks for your comment, I'll try to have a look!

Maybe two points that are worth stressing:

• we kind of like the .py file as the source of truth: easier version control, editing the .py file with VisualStudioCode (with its execution cell by cell), having JupyterBook use the .py files through Jupytext, and generating the .ipynb notebooks automatically for students following the course live when we give it
• keeping the markdown readable (i.e. no HTML <div> with some inline style that is easy to get wrong) is definitely a plus ...

[mgeier]

we kind of like the .py file as the source of truth

That's no problem for nbsphinx, Jupytext is supported, see https://nbsphinx.readthedocs.io/en/0.8.1/custom-formats.html. The box at the top of that page shows that ...

• the source file is a .py file (all Jupytext formats are supported): https://github.com/spatialaudio/nbsphinx/blob/0.8.1/doc/custom-formats.pct.py
• it's available on Binder via Jupytext: https://mybinder.org/v2/gh/spatialaudio/nbsphinx/0.8.1?filepath=doc/custom-formats.pct.py
• an .ipynb version (including auto-generated code cell outputs) is automatically created on the server: https://nbsphinx.readthedocs.io/en/0.8.1/custom-formats.ipynb
• this same .ipynb file can be viewed on nbviewer: https://nbviewer.jupyter.org/urls/nbsphinx.readthedocs.io/en/0.8.1/custom-formats.ipynb

keeping the markdown readable (i.e. no HTML <div> with some inline style that is easy to get wrong) is definitely a plus ...

Yeah, that's a bit of a trade-off ...

The example from the nbsphinx docs looks like this:

<div class="alert alert-info">

Note

This is a note!

</div>

This is not great, but IMHO it isn't too bad either.

In the py:percent format, it looks like this:

# %% [markdown]
# <div class="alert alert-info">
#
# Note
#
# This is a note!
#
# </div>

Regarding the example shown above (#152 (comment)), I would suggest a compromise:

<div class="alert alert-warning">

Tip

`random_state` parameter allows to get a deterministic results even if we
use some random process (i.e. data shuffling).

</div>


In the previous notebook, we used a k-nearest neighbors predictor. While this
model is really intuitive to understand, it is not widely used. Here, we will
a predictive model belonging to the linear model families.


<div class="alert alert-info">

Note

In short, these models find a set of weights to combine each column in the
data matrix to predict the target. For instance, the model can come up with
rules such as `0.1 * age + 3.3 * education-num - 15.1 > 0` means that
`high-income` is predicted.

</div>


Thus, we will use a logistic regression classifier and train it.

This is still somewhat readable in the source, it looks acceptable in JupyterLab and it looks quite good when using nbsphinx.

Note that nbsphinx only supports alert-info and alert-warning in the moment, but it would be easy to add more if needed.

And note that there is still a problem in nbconvert (and by extension on nbviewer), see jupyter/nbconvert#1125.