Support images with raw html syntax

[fperez]

There is some background discussion in this Jupyter notebook issue, but the gist of the issue is that nbsphinx currently doesn't recognize images declared e.g. as

<img src="images/dashboard_files_tab.png" width="791px"/>

only ones that use the plain markdown syntax:

![alt](images/dashboard_files_tab.png)

This obviously precludes passing (useful) things like custom size hints. I don't know if this is easy to fix in nbsphinx itself or if there's an underlying tool (say pandoc) that does the heavy lifting with the files... But I figured I'd mention it, it would help us use whichever syntax is more sensible in a given setting.

For now, for Jupyter we'll work around it in our docs by limiting ourselves to the ![..](..) syntax.

[mgeier]

Currently, pandoc is used to convert markdown cells, but in the not-so-near future this will probably be changed, see #36.

nbsphinx already parses raw HTML content for alert/warning <div>s (see #47 and the docs), something similar could probably be done for <img> tags.

How is this handled in nbconvert with LaTeX output?

[takluyver]

How is this handled in nbconvert with LaTeX output?

Also pandoc, so it may well have the same issue.

[mgeier]

Alternatively, <img> tags could be converted to "real" image nodes with a pandoc filter like in #35, but I don't think this has any advantage over doing it with a Sphinx Transform.

However, yet another option would be to convert all raw HTML content (not only <img> tags) to raw HTML docutils nodes.

I don't know if that would work, and I don't know if that's actually a good idea, either.

This way, the images wouldn't show up in LaTeX output.

[actsasgeek]

Was this resolved? I've taken to using the Jupyter notebook/iPython helpers but importing libraries just to show images in notebooks that are all Markdown is kind of kludgy.

Edit: I should have read more carefully. It looks like ![alt] can be used for now but it seems like the sizing information is ignored anyway (#12).

[mgeier]

@actsasgeek No, nothing has changed since then. Do you have any suggestions on how to proceed?

[fperez]

Mmh, I just ran into this issue again today, so piping in here and pinging @mpacer to see if they have any ideas...

I just checked, and running a plain jupyter nbconvert foo.ipynb with embedded <img src=... tags works fine, so the problem isn't present there. This is the nbconvert issue with related discussion.

[fperez]

A bit more info... At least with current pandoc, it seems that link_attributes are supported by nbsphinx. This means that one can write ![caption text](path/to/img.png){width="80%"} and it shows up correctly on HTML conversion.

However, in the live notebook, the extra attributes are displayed as text instead of being used (and the text is only used as alt-text, not as a caption). E.g., this:

![caption](fig/travis-free.png){width="80%"}

gives in the live notebook:

This makes me wonder: should we instead just support the pandoc-style attributes in the live notebook? I know @mpacer has thought a lot about this, and perhaps @Carreau and @takluyver have also thoughts?

note: in the nbsphinx conversion, the alt-text shows up as a caption, which surprised me but sounds actually like a good thing, it certainly would encourage better alt-text usage, I think. This is what it looks like on the HTML output:

[Carreau]

I'm all for consistent support, and would actually also prefer captions, though I don't want us to maintain our own markdown renderer in JS, at least not now :-)

If anything let push that for JupyterLab once it has been released and the classic notebook has been sunset. Then we'll have less things to patch.

[mpacer]

I could be wrong but I think that this should work for direct HTML conversion, which is the focus of the issue @fprerez linked to(jupyter/nbconvert#328), as long as the width and height are wrapped in quotes.

If this is primarily about rst intermediate output, I'll have to think about how to best solve this.

[mgeier]

AFAICT, it works with nbconvert for HTML output because this uses mistune instead of pandoc.

When using nbconvert with RST output, the same problem appears: the <img> tag vanishes.

It's probably possible to detect <img> tags in the pandoc AST and somehow turn them into proper Sphinx/docutils images with width and height specified correctly.
I'm open to a PR that does that, but I'm not going to work on that myself.

In the long run, I want to get rid of the intermediate RST (and at the same time pandoc) anyway (#36), but for that, we need an extensible CommonMark parser for Python, which to my knowledge doesn't exist yet.
I'm probably going to work on that, but not soon.

Regarding a CommonMark extension for link attributes, I would be careful not to rush into introducing the syntax that pandoc happens to use. There is quite some discussion about this in the context of CommonMark, e.g.:
https://talk.commonmark.org/t/support-for-image-dimensions/148/1
https://talk.commonmark.org/t/consistent-attribute-syntax/272
For now, I don't see anything resembling a consensus yet.
If there are any discussions going on about CommonMark extensions for Jupyter, I'd be very interested to participate.
But as @Carreau said, this should probably be done in the context of JupyterLab.

Regarding image/figure captions, this is also a pandoc idiosyncrasy: http://pandoc.org/MANUAL.html#extension-implicit_figures
If the image appears in a paragraph of its own, the alt text is turned into a figure caption.
I think this is very surprising and frankly annoying behavior, and I think we should not try to support it in the live notebook.

[fperez]

Thanks @mgeier for the extra details on the caption situation - I don't really care much for it, was just surprised to notice it.

And @mpacer, this is indeed in the context of sphinx: it works great on standalone nbconvert usage, but as @mgeier indicated, that's because the pipeline is different (mistune).

It seems at this point, the most viable path forward is the (somewhat hackish) solution proposed by @mgeier, to catch <img> in-flight and fix them up. I unfortunately don't have any cycles to try that right now, but will keep it in mind in case I clear up a weekend :)

Thanks for the input!!

[mgeier]

This issue should be fixed with #438 (since the issue didn't explicitly request the align attribute).

[mgeier]

This feature is now available in the latest nbsphinx release (version 0.7.0).