Hi!
I am thrilled to announce the first beta release of Plywood Gallery v0.0.9.
It’s a new framework to generate python documentation via notebooks.
The special feature: code snippets are represented by images.
And it’s possible to show code variations with example branching.
Here are demos of plywood-generated websites: 2D-array, functions, pathlib, napari, f-string, 3D-array, matplotlib-ImageGrid, minimal-example.
If you want to generate galleries yourself, type pip install plywood-gallery.
Setup instructions can be found in this presentation and in the plywood gallery repo.
And thanks to @Rickaym, there is a VS Code extension which allows you to insert gallery entries directly into your notebook with one click.
I took a look at just this particular example, and I have a couple of concerns. I’m not saying they’re insurmountable and I am honestly not trying to undermine your efforts, @kolibril13 , I just want to highlight some other perspectives that perhaps you haven’t considered. In the interest of arriving at an even better ultimate result.
Text-as-images
That’s actually a real problem though, as it absolutely kills accessibility. Screen readers and other assistive devices can’t do anything with code that’s displayed as a PNG image. Not to mention, even for sighted users it’s not particularly ideal.
Users with HiDPI screens will have to contend with blurry, enlarged text-screenshots when they could be seeing the content rendered using crisp, high-res font glyphs at full native display resolution.
It removes basically any ability to style the resulting content using CSS, at least nowhere near as conveniently as rich HTML would allow. (CSS filter effects can even change the color scheme of embedded images, so in theory even text displayed that way could be “styled”, but… that’s all kinds of needlessly complicating things, feels like. And even then you’re limited to styling only color — you still can’t customize font parameters, or line spacing, or any of the other things CSS can change about content between when it was generated and when it’s finally displayed to the reader.)
It boxes you into a corner with regards to internationalization, because now to translate the contents of those images you have to generate new images in each language. Translating text-as-text is a far more seamless approach to i18n (and can be crowdsourced much more easily), and it requires much, much less (a) effort and (b) disk storage to achieve the same results.
All in all, images of text content should really (IMHO) be viewed as a bad thing that’s only considered as a last resort when the text is purely decorative in nature. For actual information, it’s one of the worst decisions someone can make about how their content should be displayed.
Click-to-reveal
In addition, and separate from the above, I have to say that I’m finding it frustrating to have to click on each of the output images, to see the associated code. And the fact that, because of that, you can only see one code snippet at a time… just doesn’t seem to make for effective documentation, at least from my perspective.
Wikipedia has a policy of never “hiding” article content behind any sort of click-to-reveal interaction. (That’s permitted for article “chrome” like navboxes, and on internal project pages, but you’ll never find it in the body of an article — or if you do it should be flagged for correction, as it’s a massive violation of the Manual of Style, specifically MOS:DONTHIDE.)
The reasons why are exactly the ones I’ve raised here: It’s again an accessibility nightmare, since having the page content reconfigure itself on the fly plays havoc with how screen readers and other types of assistive devices interpret the content. And even for readers who don’t require assistive tools to browse Wikipedia, it makes the information in the article more difficult and less comfortable to consume if readers are having to click all over the place to reveal pieces of the puzzle.
Thanks a lot for this thorough feedback, I really appreciate your input!
Here are my thoughts on this:
Text-as-images
can’t do anything with code that’s displayed as a PNG image
I totally agree with that and your three points!
For text content, PNG is not the right format. I think a good alternative would be SVG.
One would only have to implement a jupyter svg capture magic for this: capture_svg · Issue #7 · Octoframes/jupyter_capture_output · GitHub
SVGs would allow HiDPI, CSS styling, and probably also internationalization.
For image content, I think PNG is a convenient format, but I am open to suggestions of other formats.
Click-to-reveal
I’m finding it frustrating to have to click on each of the output images, to see the associated code.
Thanks for sharing this, another option would be:
Hovering over images will already show the code. Clicking will set the default code. Default code will be displayed when the mouse is not hovering an image.
Regarding accessibility:
Some thoughts I had when creating the plywood gallery:
The information density should be very high, similar to cheat sheets. My idea is that there should not be a lot of code blocks cluttering the page.
I think that images close together can provide another perspectives on how the examples relate to each other than images that are further apart from each other. These galleries should not replace conventional documentation, only provide a new perspective.
In contrast to conventional documentation (which is of course great!) the plywood gallery is highlighting variations of code and their corresponding output variations. By clicking on one example and then the next example, often only one line ( or even only one word ) is changing. This makes it easy to gaps how slight image changes connect to slight code changes.
To incorporate your concerns and retain my original idea:
There could be a button “Reveal All Code” that would change the website layout to a table. First column the image, second column the code. Each row for one example. The code field at the top could still stay to reveal the code variation by clicking or hovering.
I’ll make a search bar. When typing a word, only images are shown, which are linked to code containing the searched words. Other images can either be hidden or greyed out by reducing the opacity.