diff --git a/.gitignore b/.gitignore index 7e22f15a4..a0a1a437a 100644 --- a/.gitignore +++ b/.gitignore @@ -28,4 +28,5 @@ build.xml proguard-project.txt .idea/ *.iml -user-manual +user-manual/screenshots +user-manual/output diff --git a/ui-flows/screenshots/user_manual_accounts.yml b/ui-flows/screenshots/user_manual_accounts.yml new file mode 100644 index 000000000..6c742eac1 --- /dev/null +++ b/ui-flows/screenshots/user_manual_accounts.yml @@ -0,0 +1,121 @@ +appId: com.fsck.k9.debug +--- +- launchApp: + clearState: true + +- tapOn: + id: "com.fsck.k9.debug:id/next" + +- tapOn: + id: "com.fsck.k9.debug:id/account_email" +- inputText: "fun@k9mail.example" +- tapOn: + id: "com.fsck.k9.debug:id/next" + +- tapOn: + id: "com.fsck.k9.debug:id/account_description" +- inputText: "Personal" +- tapOn: + id: "com.fsck.k9.debug:id/account_name" +- inputText: "Demo User" +- tapOn: + id: "com.fsck.k9.debug:id/done" + +- tapOn: + id: "com.android.permissioncontroller:id/permission_allow_button" + +- tapOn: "Navigate up" + +- waitForAnimationToEnd +- takeScreenshot: "user-manual/screenshots/drawer_one_account" + +- tapOn: "Settings" + +- waitForAnimationToEnd +- takeScreenshot: "user-manual/screenshots/settings_one_account" + +- tapOn: "Add account" + +- tapOn: + id: "com.fsck.k9.debug:id/account_email" +- inputText: "serious@k9mail.example" +- tapOn: + id: "com.fsck.k9.debug:id/next" + +- tapOn: + id: "com.fsck.k9.debug:id/account_description" +- inputText: "Work" +- tapOn: + id: "com.fsck.k9.debug:id/done" + +- tapOn: "Navigate up" +- tapOn: "Manage folders" + +- tapOn: "Inbox" +- tapOn: "Unify" +- back + +- tapOn: "Turing Awards" +- tapOn: "Unify" +- back +- back + +- tapOn: "Navigate up" +- tapOn: "Turing Awards" +- swipe: + direction: DOWN + +- back + +- tapOn: + id: "com.fsck.k9.debug:id/contact_picture" + index: 0 +- tapOn: + id: "com.fsck.k9.debug:id/subject" + index: 1 +- tapOn: + id: "com.fsck.k9.debug:id/subject" + index: 2 +- tapOn: + id: "com.fsck.k9.debug:id/subject" + index: 3 +- tapOn: + id: "com.fsck.k9.debug:id/delete" + +- waitForAnimationToEnd +- takeScreenshot: "user-manual/screenshots/unified_inbox" + +- tapOn: "Navigate up" +- tapOn: + id: "com.fsck.k9.debug:id/material_drawer_account_header_text_switcher" +- tapOn: "Personal" +- back + +- tapOn: "Navigate up" + +- waitForAnimationToEnd +- takeScreenshot: "user-manual/screenshots/drawer_two_accounts" + +- tapOn: + id: "com.fsck.k9.debug:id/material_drawer_account_header_text_switcher" + +- waitForAnimationToEnd +- takeScreenshot: "user-manual/screenshots/drawer_account_list" + +- tapOn: + id: "com.fsck.k9.debug:id/material_drawer_account_header_text_switcher" + +- tapOn: "Settings" + +- waitForAnimationToEnd +- takeScreenshot: "user-manual/screenshots/settings_two_accounts" + +- tapOn: "Work" + +- waitForAnimationToEnd +- takeScreenshot: "user-manual/screenshots/account_settings" + +- tapOn: "More options" + +- waitForAnimationToEnd +- takeScreenshot: "user-manual/screenshots/account_settings_menu_expanded" diff --git a/user-manual/README.md b/user-manual/README.md new file mode 100644 index 000000000..99df45800 --- /dev/null +++ b/user-manual/README.md @@ -0,0 +1,28 @@ +# User Manual Tooling + +This directory contains scripts to automate creating screenshots for the [user manual](https://docs.k9mail.app/) whose +source can be found in the [k9mail-docs](https://github.com/k9mail/k9mail-docs) repository. + +## Requirements + +- [Bash](https://www.gnu.org/software/bash/) +- [Maestro](https://maestro.mobile.dev/) +- [ImageMagick](https://imagemagick.org/)'s `convert` command line tool + +## Usage + +1. Start an emulator with the following configuration: + + - Device: Pixel 2 + - Size: 1080x1920 + - Density: 420 dpi + - API 33 "Android 13.0 (Google APIs)" - not "… (Google Play)" + +2. Run `./build_images.sh` + + This will enable [System UI Demo Mode](https://android.googlesource.com/platform/frameworks/base/+/master/packages/SystemUI/docs/demo_mode.md) + on the emulator, run the Maestro flows `ui-flows/screenshots/user_manual*` to record screenshots, then run a + post-processing step on the screenshots. + +3. The final images can be found in the `output` directory. Copy as necessary to the + [k9mail-docs](https://github.com/k9mail/k9mail-docs) repository. diff --git a/user-manual/build_images.sh b/user-manual/build_images.sh new file mode 100755 index 000000000..da2bef737 --- /dev/null +++ b/user-manual/build_images.sh @@ -0,0 +1,27 @@ +#!/bin/bash +set -e + +SCRIPT_PATH="$( cd -- "$(dirname "$0")" >/dev/null 2>&1 ; pwd -P )" + +# Enable and configure SystemUI demo mode +adb shell settings put global sysui_demo_allowed 1 +adb shell am broadcast -a com.android.systemui.demo -e command enter +adb shell am broadcast -a com.android.systemui.demo -e command clock -e hhmm 1200 +adb shell am broadcast -a com.android.systemui.demo -e command network -e wifi show -e level 4 +adb shell am broadcast -a com.android.systemui.demo -e command network -e mobile show -e level 4 -e datatype lte +adb shell am broadcast -a com.android.systemui.demo -e command battery -e level 100 -e plugged false +adb shell am broadcast -a com.android.systemui.demo -e command notifications -e visible false + +pushd "${SCRIPT_PATH}/.." + +# Build and install app +./gradlew :app:k9mail:installDebug + +# Record screenshots +maestro test ui-flows/screenshots/user_manual_account_setup.yml +maestro test ui-flows/screenshots/user_manual_accounts.yml + +# Post-process screenshots +user-manual/process_screenshots.sh + +popd diff --git a/user-manual/process_screenshots.sh b/user-manual/process_screenshots.sh new file mode 100755 index 000000000..0e059fcbe --- /dev/null +++ b/user-manual/process_screenshots.sh @@ -0,0 +1,30 @@ +#!/bin/bash +set -e + +SCRIPT_PATH="$( cd -- "$(dirname "$0")" >/dev/null 2>&1 ; pwd -P )" + +pushd $SCRIPT_PATH + +mkdir -p output/setup/img/ +cp screenshots/welcome_screen.png output/setup/img/ + +mkdir -p output/accounts/img/ + +cp screenshots/account_setup_* output/accounts/img/ +cp screenshots/drawer_account_list.png output/accounts/img/ + +# Adding another account +convert screenshots/drawer_one_account.png -stroke red -strokewidth 5 -fill none -draw "rectangle 20,1750 820,1840 " output/accounts/img/drawer_settings_highlight.png +convert screenshots/settings_one_account.png -stroke red -strokewidth 5 -fill none -draw "rectangle 20,580 1060,690 " output/accounts/img/settings_add_account_highlight.png + +# Switching between multiple accounts +convert screenshots/unified_inbox.png -crop 1080x660+0+0 -stroke red -strokewidth 5 -fill none -draw "rectangle 20,85 130,190 " output/accounts/img/message_list_drawer_button_highlight.png +convert screenshots/drawer_two_accounts.png -crop 1080x650+0+0 -stroke red -strokewidth 5 -fill none -draw "rectangle 720,360 815,455 " output/accounts/img/drawer_account_switcher_highlight.png + +# Removing an account +convert screenshots/drawer_two_accounts.png -stroke red -strokewidth 5 -fill none -draw "rectangle 20,1750 820,1840 " output/accounts/img/drawer_two_accounts_settings_highlight.png +convert screenshots/settings_two_accounts.png -stroke red -strokewidth 5 -fill none -draw "rectangle 20,580 1060,735 " output/accounts/img/settings_second_account_highlight.png +convert screenshots/account_settings.png -crop 1080x485+0+0 -stroke red -strokewidth 5 -fill none -draw "rectangle 980,85 1060,190 " output/accounts/img/account_settings_menu_highlight.png +convert screenshots/account_settings_menu_expanded.png -crop 1080x485+0+0 -stroke red -strokewidth 5 -fill none -draw "rectangle 570,110 1050,210 " output/accounts/img/account_settings_remove_account_highlight.png + +popd