Documentation Automated Screencapture

A brain dump and notes on ideas for automating the creation of screenshots for the Koha manual.
== Aim ==
The current situation: 
* There are about 1473 images in the manual images folder [as at 2018-10-03]. 
* Many screenshots are probably outdated and don't reflect the current version of Koha. 
* Recreating all the screenshots manually is time consuming. 
* There is different sample data depending on who and when the screenshots were taken. 
* Adding annotations is time consuming. 
* Only covers US English interface. 
* There are inconsistencies in screen size used when capturing screenshots.
The desired result:
* Updated screenshots are automatically generated for each new Koha release.
* The same sample data is used each time.
* Ability to generate screenshots for multiple languages, with example data in the appropriate language as well. 
==Options==
===Option 1 - Selenium + Robot Framework + Screenshot library===
This option lets you:
* Automatically generate screenshots, including specific areas based on css classes.
* Add sample data, for example: show the fields with the data to be added before submit is pressed.
* Incorporate annotations, such as numbers or text boxes. 
How it works:
* You have a 'resource' file (resources.robot) that includes variables and common 'keywords'. This can include the URL for the Koha site, usernames and passwords, common tasks such as logging in.
* You have test scripts that create the required screenshots (filename.robot). For example: log in to the staff client, go to a page, click this button, enter this data, capture screenshot of area required.
* You run the tests.
* Screenshots are generated.
* Report generated to show if tests passed or failed. 
Repository with example scripts: TO ADD
Advantages:
* Automates screenshot capture.
* Meets most of the aims.
* Can version control of test scripts.
* Repeatable process once your computer is setup with the required components. 
Disadvantages:
* There may be some screenshots that require manual creation.
* Initial work required to setup script for screenshot capture.
* May need to have a process for casual contributors, for example: have a temp image folder where screenshots are added, documentation team create or update scripts to generate automatically.
The components:
* Python: programming language
* Selenium: a web testing tool that lets you write a script with things you want to test, and then indicates whether it passed or failed. 
* Robot Framework: works with Selenium and is more 'user friendly' to setup test scripts, rather than needing to create a Python script. 
* Screenshot library: a library that works with the Robot Framework to enable screen captures. 
Setup for Ubuntu Linux 18.04:
* Install Python 3 (generally already installed: test to see with python3 --version)
* Install pip3 (way to install python libraries): sudo apt-get install pip3
* Install Selenium: pip3 install selenium
* Install Robot Framework: pip3 install robotframework
* Install XXX (can't remember what this is): pip3 install robotframework-selenium2library
* Install library for screen capture: pip3 install XXX
* Install selenium browser driver for Firefox: TO UPDATE
* Add to $PATH (Linux): TO DO 
Links: 
* Selenium: https://selenium-python.readthedocs.io/index.html
* http://robotframework.org
* https://github.com/robotframework/robotframework/blob/master/INSTALL.rst#python-2-vs-python-3
* http://robotframework.org/robotframework/latest/libraries/Screenshot.html
* https://robotframework-selenium2screenshots.readthedocs.io/en/latest/_downloads/keywords.html - arguments for Selenium2Screenshots 
* Other links and tutorials:
** Automating Screenshots in Documentation: https://blog.codeship.com/automating-screenshots-in-documentation/
** Selenim with Python tutorial: https://selenium-python.readthedocs.io/index.html
** Selenium online training (not yet tested): https://www.tutorialspoint.com/selenium_online_training/index.asp 
** Sphinx + Robot Framework = documentation as result of functional testing https://sphinxcontrib-robotframework.readthedocs.io/en/latest/index.html
** https://www.slideshare.net/plewicki/sphinx-robot-framework-documentation-as-result-of-functional-testing
** Presentation to robocon18: https://datakurre.github.io/robocon2018/ 
Writing tests (see repository for examples):
* resource.robots - common variables and keywords that test scripts can reuse
* filename.robot - scripts to complete fields and capture screenshots, can be grouped in separate files 
Where used:
* Used for Python documentation - TO DO add link 
Integration with Sphinx:
* https://sphinxcontrib-robotframework.readthedocs.io/en/latest/index.html - Basically, you can incorporate the tests into the actual manual files when using restructured test. 
===Option 2 - Wraith (yet to test)===
Wraith - compares two images and sees if there are any differences: https://github.com/BBC-News/wraith http://bbc-news.github.io/wraith/ 
TO DO - add more detail
===Option 3 - Cucumber===
Joubu investigate automating screenshots some time ago - see mailing list thread https://lists.katipo.co.nz/public/koha/2018-January/049807.html and https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=13849
This was also related to improving testing in Koha.
Cucumber: A behaviour-driven development (BDD) tool - see https://docs.cucumber.io/ and https://cucumber.io/blog/2017/05/15/intro-to-bdd-and-tdd
TO DO - add more detail
==Other things==
===Optimising image sizes===
Optimise images using pngcrush (reduced image folder size from 82.3 MB to 54.6 MB - about a 33% reduction in size). 
Script to go through folder and minimise images using pngcrush: https://gist.github.com/tony-landis/3909387 
TO DO: identify a suitable jpeg optimsation tool:
* mozjpeg? https://github.com/mozilla/mozjpeg https://images.guide/ Guide about image optimisation
==TO DO==
* Add numbers and annotations (see slide 19 in presentation above + docs)
* Generate images locally as part of building documentation - investigate further
* Images that can't be automatically captured - how to identify and make sure updated images created
* Image optimisation - decide on a jpeg optimisation tool
* Setup - complete this and test!
* Find link again for how used in Python documentation
* Add more detail to Cucumber and Wraith options
* Identify other options