Closed (fixed)
Project:
User Guide
Version:
8.x-0.x-dev
Component:
Scripts
Priority:
Normal
Category:
Task
Assigned:
Reporter:
Created:
25 Jul 2015 at 21:48 UTC
Updated:
20 Sep 2016 at 17:44 UTC
Jump to comment: Most recent
Problem/Motivation
It would be good to be able to automate, as much as possible, the creation of screen shots for the User Guide.
Ideally, we would be able to create them automatically in any language.
Proposed resolution
A proof of concept has been created in this issue, which does the following:
- There's a module in this project, containing a Simpletest test for each language.
- You add this project to your modules directory, and install/enable the Testing module.
- There's also a JavaScript script that runs with the Firefox Greasemonkey plugin. You'll need to install the Greasemonkey plugin in Firefox and import the script.
- You run the test, which is called "UserGuideDemoTestEn" (for English, or a different suffix for a different language), interactively, from admin/config/development/testing.
- When it's done, under the output, the Greasemonkey script adds a form to the page that asks you to enter some information for making screenshots, such as where you want to put them.
- You click the button in the form, and it outputs a shell script.
- You can then copy/paste the commands into a script file, and run the script at a Linux command line.
Remaining tasks
The proof of concept for English and Spanish has been committed to the Git repo. Stil to do:
a) Write the rest of the Simpletest test so it builds the demo site.
b) Add screenshot calls to this test to generate each of the needed screen shots. For each one, you need to know the page path, the image file name, and the coordinates/size to shoot. You can figure out the coordinates using the web development toolbar plugin in Firefox - under Miscellaneous it has a handy-dandy ruler that you can use to draw a box and figure out the size and the offset of it, relative to the HTML page (which is what you'll need).
Note on this: in testing, red arrows (or boxes) were deemed to be very useful. So as I automate screenshots, I need to either make them smaller so they only show the portion of the screen that is being referred to, or put in red boxes to highlight the portion(s) being referred to (arrows are hard to automate but boxes can be done).
I'm not sure how transferable it will be from person to person and browser to browser, because the pixel coordinates are probably slightly different from OS to OS, and Greasemonkey only runs on Firefox.
c) Figure out a way to export the database and sites/default/files directory also at the end of the test, so people could import the demo site.
d) Make test classes for other languages, when we're ready to do them. This will require translating the scenario text to other languages, which goes at the top of the test class. Other that that, the test class is just a few lines, calling a method in the base class that actually generates the site.
Comments
Comment #1
jhodgdonAdding another To Do.
Comment #2
jhodgdonOK I got the basic proof of concept committed. I think it's viable, though I am not sure about how to run foreign languages.
Comment #3
jhodgdonAdding to summary about current status and also languages.
Comment #4
jhodgdonComment #5
diana.lakatos commentedAutomatically updated screenshots could be implemented with WalkHub.
When you create a Walkthrough with WalkHub (by clicking through your scenario, adding/editing content in fields, etc.), a screenshot of each step and a widget from the screenshots are automatically created. They are updated periodically as specified.
To make it work for the user guide, we'd probably need stand-alone screenshots (not the widget) that update periodically, we have already implemented this solution for a client.
Multiple languages are not yet supported, but can be solved with parameters, another built-in functionality that lets you select the environment a Walkthrough is played on. We are planning to support multiple languages, but this is only planned for a later phase of the project — so if language support could be added at a later time, this could work as well.
If you'd like to, we can schedule a meeting where we can show you how WalkHub works and discuss the requirements for this project.
Comment #6
jhodgdonDiana - thanks but I do not think we really want to rely on a commercial, 3rd-party tool for this project. Also as far as I know it will not take screen shots of part of a page, only the whole page.
Comment #7
jhodgdonRegarding multiple languages, it should be possible to do using Simpletest. Example of a test that installs Drupal in another language is InstallerTranslationMultipleLanguageTest (thanks GaborHotsy in IRC). I will take a look at this.
Comment #8
jhodgdonI ran into this bug with the non-English languages: #2541800: Some config do not inherit from config_object, so locale_system_set_config_langcodes() results in schema errors... but it may still work if I can get that worked out...
Comment #9
jhodgdonI was able to get around this bug, and my proof-of-concept for English and Spanish are both working, inheriting from a base class. I think this approach will work. It's not *totally* automated, and the Simpletest tests take a while to run, but it's definitely better than making the screen shots by hand. There may be a few we'll still have to do by hand (like screen shots of the install screens, since Simpletest install isn't interactive so doesn't hit them), but it's way better than doing them all by hand.
I'll commit what I have now, which is a complete proof of concept. Still to do:
- Build the rest of the demo site in Simpletest. My proof of concept just does the Site Information screen (site name, slogan, site email).
- As the topics get written, put in the actual screen shots that are needed (with file names, etc.).
- Eventually we'll need to translate the scenario text into the other languages, but that can be done as we add them.
Comment #10
jhodgdonUpdating summary.
Comment #11
jhodgdonI had another thought on this. Some of the screenshots will require things like "Go to this page, and click the Pencil icon to turn on the links", or "Go to this page, and take a screen shot with this drop-down open".
It seems like these would need to be done manually, but actually I think these types of instructions could be automated if we injected a little bit of JavaScript (using JQuery) into the HTML dump produced by SimpleTest, which should be possible to do. I'll have to try it out.
Comment #12
jhodgdonI did some more work on screenshot automation the last few days.
It turned out that there was a problem with the non-admin page screenshots, having to do with when Simpletest removes the file uploads directory, which contains (among other things) the color CSS file for Bartik. So I had to override the public files directory. That seemed to work.
I'm now having a problem with the Spanish proof of concept. It is downloading the .po translation file from localize.drupal.org, but doesn't seem to be reading it in, or at least it is not using it to translate the UI. I'm not sure what is going on there, but the screen shots of admin screens have English all over them. So I'll eventually have to figure that out.... not an urgent priority I guess.
Anyway, I did figure out how to get JavaScript added to the page, so I can do things like hide/show portions of the page, scroll down to the bottom, etc. So I think at least for English, aside from the install screens, we should be able to reproduce all necessary screen shots. I still need to finish making the test but I've committed what I've done so far.
Comment #13
jhodgdonNote: I filed an issue about the problem I was having in Spanish: #2583697: Fatal error running some tests in UI with locale.module enabled. This issue was marked as a duplicate of #2573975: function_exists check in PluralTranslatableString is wrong. Adding comment so I don't lose track of these issues.
Anyway, I'm getting back to work on this!
Comment #14
jhodgdonI just made another commit on this issue. I have the Spanish version working now, plus or minus a few interesting bits of code. Anyway. What remains is to code up the rest of the site build, and the screenshots.
Comment #20
jhodgdonAdding a note to the To Dos -- in testing, red arrows (or boxes) were deemed to be very useful. So as I automate screenshots, I need to either make them smaller so they only show the portion of the screen that is being referred to, or put in red boxes to highlight the portion(s) being referred to (arrows are hard to automate but boxes can be done).
Comment #25
jhodgdonI just made a pretty big commit on this issue, which updated images in a number of files with automated screen shots! I'm still working through the rest of the guide, but I finally have a really robust procedure for the automation that is only minimally dependent on things like browser width, and should hold up well to multiple languages.
Woot!
I hope it's OK to go ahead and commit updated images (I'm reviewing them carefully and they're going through several iterations).
I'm also keeping track of which images need to be generated manually -- this list is in source/en/images/README.txt and so far consists of:
- Running the installer
- For obscure reasons, the screen shot of the vertically-oriented toolbar in the config-overview topic
- In-place editing
Comment #46
jhodgdonWOOOOOOT! I have just committed the very last batch of the automated screenshot images and code!