Sunday, February 7, 2021

I pushed my work of the last days (for #632) to master of lino and book.

About screenshots

For the first time in the history of Lino I got the lino.api.selenium.runserver() function working. It is a bit tricky because I wanted it to launch a Django development server in the background, then use selenium to open a headless firefox and run an automated “tour” in the demo database, taking screenshots on the go. And these screenshots would then be available for being included in documentation pages.

Here is an example of such a screenshot:

../../_images/contacts.Companies.grid.params_en.png

This screenshot is taken from A tour of the Noi/ExtJS demo project.

But of course every fixed issue causes new questions to raise.

I had to figure out how to organize everything. Where to store those tours? They are no longer under /docs/tours. I started to care about internationalization: we don’t need “just screenshots”, we need them in different languages. The selenium code that runs the tour is now language-agnostic and the same tour is run for different users. I converted the maketour.py script into a script to be executed with pm run. I renamed lino.api.selenium.Album to lino.api.selenium.Tour. I added a test case that actually runs our first maketour.py script of the noi1e project.

Where to hook the tours into the doc tree? They are neither “Specs” nor “API”. Each tour creates one .rst page, that page is meant as a reference for the author of application documentation. It describes how the tour has been done, which screenshots are available, and it gives the names of the image files.

I removed the tours index page (which was meant to list all the tours) because that was a useless file to maintain. Rather hook them into the specs of the application they describe. So the noi1e tour is now in the Lino Noi Developer Guide section.

I added code in test_demo.py that runs the noi1e tour.

I had all this working, but after a system upgrade on my notebook (where also firefox was updated) it stopped to work again. After another hour of trying to get it back to work, I decided to abandon, comment out the lines in test_demo.py that would run this test, and put it to sleep again. After all this is not urgent.

TODO:

  • convert the make_screenshots.py scripts in lino_weleup and lino_welcht to maketour.py scripts in the gerd and mathieu demo projects.

  • extend the noi1e tour to have more screenshots

  • write a tour for a react demo

  • write a tour outside of the book in an independent application, e.g. amici.