Thanks @cmarmo, the rendering does look better.

I'm not super experienced here, but I'm a little bit concerned about injecting raw html into the .rst. I guess that's fine in the about page because it won't change too much, but here we would have to handle the html code on top of the narrative docs which may become unfeasible.

Is there a way to handle this purely in sphinx? Maybe using the figclass attribute of the figure? https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure (again, I don't have a clear idea of what would work here)

If really that sounds too complex, then I'd suggest to drop the side-by-side layout and just have pictures and code aligned vertically.

Thanks.

There seem to be some html left in supervised_learning.rst

I'm quite skeptical about the maintainability comment, because I don't find the website, as of today, easily maintainable in general.

I mean that mixing narrative docs + html is something that will hurt maintainability in the long run. As of today, we have zero html manually injected in our narrative docs, and I think that's for the better. I wasn't talking about the website. I definitely believe you if you say it's hard to maintain.

I would appreciate a quick merge or just a rejection. Thanks.

I'm doing my best by reviewing this @cmarmo. Thanks for your work so far.

EDIT sorry pressed enter too soon

made a few comments, otherwise LGTM

thanks @cmarmo !

Looks much better already