Jupyter-book: Accessibility for the Jupyter Book interface

[choldgraf]

We should ensure that Jupyter Book is as accessible as possible out-of-the-box. My guess is that right now, it is not, and this is supported by this accessibility audit:

http://wave.webaim.org/report#/https://jupyterbook.org/intro

It would be fantastic to improve upon some of the easier things from the audit above, so that most accessibility issues are dealt with early on.

[cycomachead]

When you get more into this, if you want any advice: Shoot me an email and I'm happy to provide support, and am on campus so I'm happy to meetup! I've done a lot of work in the past and am happy to help here, though I may not yet have time to write code.

[choldgraf]

hey @cycomachead - I'd love to grab a coffee and chat about this soon if you'd be willing. There are a number of a11y efforts in the Jupyter community now and perhaps you'd be interested to hear about them?

[bmcfee]

I had a more specific question about this: is there a recommended method to specify alt text? I'm thinking specifically of inline-rendered notebook figures and embedded html5 animations, but I would expect this problem to pop up with any kind of media object. I didn't see anything in the documentation about it, and nothing's immediately obvious from the ipython side of the docs as well.

(Tacking on here since it seems like an appropriate existing issue, but I'm happy to relocate to a new issue if that would be better.)

[cycomachead]

If you're using markdown then this should work:

![image-alt-text](image.url)

[choldgraf]

@bmcfee - I feel like this is an issue that each library would need to figure out for themselves when it comes to outputting an HTML bundle. For example, best-practice would be to include an alt-tag for any images that are being output in a notebook. Jupyter Book is just going to directly convert those outputs into the HTML that's seen on each page.

For example, I just opened up an issue to discuss this in Matplotlib (https://github.com/matplotlib/matplotlib/issues/15971), I imagine it'd be a similar fix in other packages.

[bmcfee]

Circling back on this, @choldgraf I think you're right that it probably belongs in each plotting library, but it seems unlikely to be implemented any time soon. It'd be nice to have an override option for users that really need this, even if it's less than elegant.

Nbconvert does seem to support cell output image alt tags (in a limited form) via cell tags: https://github.com/jupyter/nbconvert/pull/1112 but threading that through sphinx seems like a bit of a challenge. (I tried this locally with a book build and it didn't work.)

[choldgraf]

I think the way that it'd be best to handle alt-tags in matplotlib images _right now_ would be to use glue functionality. glu:figure lets you paste in a figure that was generated by your code (assuming you're writing in python) and then you can attach other kinds of image-y things to it (like alt-tags etc). Wanna try that and see how clunky it is? https://jupyterbook.org/content/glue.html#the-glue-figure-directive

[bmcfee]

Interesting suggestion! I don't see how to put alt-text in a glued figure though?

[choldgraf]

If it's not possible, then we should add it - here's where we're adding in the sphinx figure node:

https://github.com/executablebooks/MyST-NB/blob/master/myst_nb/nb_glue/domain.py#L196

I think there we should figure out a way to add an alt text since it is possible in the rst figure directive

that said, can you try just adding alt and see if it works?

[bmcfee]

No dice:

/home/bmcfee/git/dstbook/content/ch05/Cosine.ipynb:70002: WARNING: Directive 'glue:figure': Unknown option: alt

[choldgraf]

bummer! OK then wanna open an issue in MyST-NB about adding an alt option to the glu:figure directive?

[choldgraf]

awesome! and just a note that if you get this working, you could even have the code and the "glued" figure on the same page. Just add a remove-cell to the code cell that generates the figure (or a remove-output anyway) and the glu:figure code in a markdown cell just underneath

[whitead]

I noticed that nbconvert now has support to add alt text via cell metadata. However, somewhere in the jupyter book build process these are clobbered with the path to the image. Is there anyway to prevent this? Thanks!

[chrisjsewell]

Well thats quite possibly because jupyter book does not use nbconvert 😆
But have no fear, we/I will be looking into supporting "output formatting" via cell metadata in the near future. Let me know if there is any metadata formatting that you would find particularly helpful? 😄

[whitead]

@chrisjsewell Ah, missed that😄. Probably the main ones would be alt, aria-describedby, aria-label and aria-labelledby which would help alt text on plots and pointing to descriptions of code output. I'm happy to do a PR on this if you can point me in the right direction.

[choldgraf]

Most of the accessibility changes in Jupyter Book would probably need to be in the HTML templates for the sphinx-book-theme here:

https://github.com/executablebooks/sphinx-book-theme/tree/master/sphinx_book_theme

Another possibility is to add accessibility metadata when myst-nb converts notebook outputs etc into docutils nodes. Maybe somewhere around here:

https://github.com/executablebooks/MyST-NB/blob/master/myst_nb/converter.py