Add mdbook-slide-evaluator

[michael-kerscher]

I created a first implementation for the mdbook-slide-evaluator I described in #2234.

This is still not finished but I wanted to provide a chance to review the current state.

One has to run a webdriver compatible browser (e.g. selenium-chromium) so the slides can be rendered. The browser can access the file either via a file:// or http:// uri.

The tool grabs the configurable element from that page and evaluates the size of this element. Output can be stored in a csv file or at stdout and looks like this at the moment:

$ mdbook-slide-evaluator book/html/android/aidl
book/html/android/aidl/birthday-service.html: 750x134
book/html/android/aidl/example-service/changing-definition.html: 750x555
book/html/android/aidl/example-service/changing-implementation.html: 750x786
book/html/android/aidl/example-service/client.html: 750x1096
book/html/android/aidl/example-service/deploy.html: 750x635
book/html/android/aidl/example-service/interface.html: 750x570
book/html/android/aidl/example-service/server.html: 750x837
book/html/android/aidl/example-service/service-bindings.html: 750x483
book/html/android/aidl/example-service/service.html: 750x711
book/html/android/aidl/types/arrays.html: 750x291
book/html/android/aidl/types/file-descriptor.html: 750x1114
book/html/android/aidl/types/objects.html: 750x1258
book/html/android/aidl/types/parcelables.html: 750x637
book/html/android/aidl/types/primitives.html: 750x366
book/html/android/aidl/types.html: 750x197

It is also capable of storing screenshots of the evaluated element to have a manual view.

Possible improvements:

• use data:// uris in which the html page is encoded to avoid having complicated mount into a selenium docker container or needing to serve the pages via http. A problem is, that external files (e.g. css, etc.) are linked. With this data:// uri type the browser would not need any access to files or http.
  • I evaluated https://crates.io/crates/inline-css for this job and this almost worked, but some things are still looking not correct, so I did not include it here but will later.
  • This code can be found in webclient-data-uri
• have a look at included editors with rust code to see if these have a scrollbar (might be possible with some js code that returns this info)

[djmitche]

This is pretty cool!

[michael-kerscher]

I'm actually not sure if this repository is the best choice for this tool or if should be in a different/separate repo

[mgeisler]

Hey @michael-kerscher, let me just say that this looks super cool! It's impressive that you can get this done with so little code 😄 Thanks a lot!

I haven't had a change to try it out myself, but it seems the dependencies are just a Docker container with Selenium. That's cool and it should be something I could also run without Docker, right? Perhaps using python3-selenium from Debian? I'll eventually play around with this, but Docker is fine for GitHub CI.

[mgeisler]

I think you need to install dprint locally and run dprint fmt. We have instructions for that in our README or CONTRIBUTOR file.

[mgeisler]

I'm actually not sure if this repository is the best choice for this tool or if should be in a different/separate repo

It takes a few steps for us to create new repositories in the google/ GitHub organization, so I would suggest putting it into a subdirectory here for now. You're of course more than welcome to go through those steps and create a new repository for the tool! It just requires filling out some forms and so on...

[michael-kerscher]

Hey @michael-kerscher, let me just say that this looks super cool! It's impressive that you can get this done with so little code 😄 Thanks a lot!

I haven't had a change to try it out myself, but it seems the dependencies are just a Docker container with Selenium. That's cool and it should be something I could also run without Docker, right? Perhaps using python3-selenium from Debian? I'll eventually play around with this, but Docker is fine for GitHub CI.

You don't really need a docker container, yes.
You only need something that speaks webdriver and this can also be e.g. a native on your system managed by e.g. webdriver-manager that installs this on your system. python3-selenium is leveraging the locally installed e.g. chromedriver but does not bring it with itself. Both combine though.
I added an example to the Readme.md

[michael-kerscher]

What still needs some work is some actual policy that is evaluated. E.g. defining a threshold for how many pixels the height can be

[michael-kerscher]

To put some numbers here, the current full book with all pages that have a main element are evaluated in about 3 minutes when rendered with selenium/standalone-chromium:latest

real    3m3.411s
user    0m1.484s
sys     0m0.132s

[michael-kerscher]

This seems to be ready for the intended use case now.

[mgeisler]

This seems to be ready for the intended use case now.

Thanks for the example in the README, I'll give it a go!

[mgeisler]

I tried this locally with the Python instructions and it's cool!

Let us merge this now so we have something to build on. Things to look at implementing later:

• A small integration test for this, something we can run in GitHub to protect against bit rot. It could be something which evaluates a single static HTML file.
• The GitHub integration which can be run on PRs to warn authors about too large pages. I think it would be useful if we could show the delta in size, something like "This PR increases the slide height by 20px". If we can do that, we can avoid annoying people when they fix typos in an already large slide.