Documentation improvements

- Simplify language and use shorter phrases.
- Merge android stuff into one page "Android development".
- Update macOS/Linux instructions to be on par with Windows.

docs/building/build_project.md

@@ -1,18 +1,16 @@
 # Build project
 
-For instructions on setting up environment, see:
+First follow instructions to set up environment:
 
 * [Windows setup](./windows_setup.md)
 * [macOS and Linux setup](./macos_linux_setup.md)
 
-## Build for Android
-
-Open terminal in project root and run:
+Then open terminal in project root and run:
 
     flutter build apk --release
 
 After building, you can find APK here:
 
     dist/android/release/roc-droid-<version>.apk
 
-Upload APK file to device and tap on it to install.
+You can upload it to device and tap to install.

docs/building/macos_linux_setup.md

@@ -18,7 +18,17 @@
 
 ## Install Android Studio
 
-* Installing Android studio: <https://developer.android.com/studio#downloads>
+* Installing Android Studio using `brew` (macOS or Linux):
+
+    * `brew install --cask android-studio`
+
+* Installing Android Studio using `snap` (Ubuntu):
+
+    * `sudo snap install android-studio --classic`
+
+* Installing Android Studio manually:
+
+    * <https://developer.android.com/studio#downloads>
 
 * Installing Android SDK Command Line Tools from Android SDK Manager ([adopted from Stack Overflow](https://stackoverflow.com/questions/64708446/)):
 
@@ -36,9 +46,9 @@
 
     * Check the box: `Android SDK Command Line Tools` and click `Apply` to install.
 
-## Install Android SDK without Android Studio
+## Install Android SDK (without Android Studio)
 
-If you don't need Android Studio, you can install Android SDK without using GUI.
+If you don't use Android Studio, you can install Android SDK standalone.
 
 * Installing Android SDK using `brew` (macOS or Linux):
 
@@ -48,10 +58,38 @@ If you don't need Android Studio, you can install Android SDK without using GUI.
 
     * `sudo snap install androidsdk`
 
-* Installing Android SDK manually: https://thanhtunguet.info/posts/how-to-install-android-sdk-android-cmdline-tools-without-android-studio/
+* Installing manually: <https://thanhtunguet.info/posts/how-to-install-android-sdk-android-cmdline-tools-without-android-studio/>
+
+## Install JDK
+
+For Android build, we require **JDK 17** or later.
+
+* Installing OpenJDK using `brew` (macOS or Linux):
+
+    * `brew install openjdk@17`
+
+* Installing OpenJDK using `apt` (Ubuntu):
+
+    * `sudo apt install openjdk-17-jdk`
+
+* Installing OpenJDK manually:
+
+    * Documentation: <https://openjdk.org/install/>
 
 ## Setup Flutter
 
+* Configure Android Studio path (if you've installed it):
+
+    * `flutter config --android-studio-dir="/opt/android-studio"` (specify correct directory)
+
+* Configure Android SDK path (if you've installed standalone sdk):
+
+    * `flutter config --android-sdk="/opt/android-studio"` (specify correct directory)
+
+* Configure JDK path:
+
+    * `flutter config --jdk-dir "/usr/lib/jvm/java-17-openjdk-amd64"` (specify correct directory)
+
 * Run: `flutter doctor --android-licenses` (we agree to all license terms)
 
 * Run: `flutter doctor` - and make sure that all tests pass successfully (status: No issues found!)

docs/building/windows_setup.md

@@ -13,25 +13,21 @@ Official documentation: <https://chocolatey.org/install>
 
 ## Install Flutter
 
-* Installing Flutter using `Chocolatey`
+* Installing Flutter using `Chocolatey`:
 
     * Run in `PowerShell` with administrator rights: `choco install flutter`
-
-        (Chocolatey will update PATH automatically).
 
 * Installing Flutter manually:
 
-    * Flutter SDK installation: <https://flutter.dev/docs/get-started/install/windows>
-
-    * Setting up a global environment for Windows: <https://flutter.dev/docs/get-started/install/windows#update-your-path>
+    * Follow official documentation: <https://flutter.dev/docs/get-started/install/windows>
 
 * To update Flutter, use: `flutter upgrade`
 
 ## Install Android Studio
 
 * Installing Android studio: <https://developer.android.com/studio#downloads>
 
-* Installing Android SDK Command Line Tools from Android SDK Manager ([adopted from Stack Overflow](https://stackoverflow.com/questions/64708446/)):
+* Installing Android SDK Command Line Tools from Android SDK Manager ([adopted from stackoverflow](https://stackoverflow.com/questions/64708446/)):
 
     * Open android studio
 
@@ -45,38 +41,31 @@ Official documentation: <https://chocolatey.org/install>
 
     * Select SDK Tools sub-tab.
 
-    * Check the box: `Android SDK Command Line Tools` and click `Apply` to install.
-
-## Setup Java
-
-* Typically, Android Studio installs the required version of Java, which is needed for the correct operation of Flutter and the studio itself. But as an additional condition for the correct operation of the application, a certain version of JDK (Java development kit) is required.
-
-  * The currently required JDK version is: **17**
-
-  * This JDK should be installed in addition to the JDK that is used by Android Studio and Flutter in cases where the two JDK versions differ.
+    * Check the box: `Android SDK Command Line Tools` and click `Apply` to install
 
-* Download and install JDK from this link: [Oracle - Java Downloads](https://www.oracle.com/java/technologies/downloads/#java17)
+## Install JDK
 
-## General Flutter setup
+* By default, Flutter uses Java shipped with Android Studio, which may be too old. For Android build, we require **JDK 17** or later. 
+
+    Download and install it from here: [Oracle - Java Downloads](https://www.oracle.com/java/technologies/downloads/#java17).
 
-* Run in `PowerShell` with administrator rights: `flutter config --android-studio-dir="C:\Program Files\Android\Android Studio"` (specify directory)
+## Flutter setup
 
-* Run in `PowerShell` with administrator rights: `flutter doctor --android-licenses` (we agree to all license terms)
+* Configure Android Studio path:
 
-* Run in `PowerShell` with administrator rights: `flutter doctor` - and make sure that all tests pass successfully (status: No issues found!)
+    * Run in `PowerShell` with administrator rights: `flutter config --android-studio-dir="C:\Program Files\Android\Android Studio"` (specify correct directory)
 
-## Setting up the Flutter Java environment
+* Configure JDK path:
 
-* The Flutter project detects the JDK version to use via Android studio settings. This means that in most cases the version automatically detected by Flutter will be incorrect. To solve this problem, explicitly specify the JDK version.
+    * Run in `PowerShell` with administrator rights: `flutter config --jdk-dir "C:\Program Files\Java\jdk-17"` (specify correct directory)
 
-* To specify JDK version call in the project directory: `flutter config --jdk-dir "<Current Java JDK folder>"`
+        * Example of a successful result: `Setting "jdk-dir" value to "C:\Program Files\Java\jdk-17". You may need to restart any open editors for them to read new settings.`
 
-    * Example: `flutter config --jdk-dir "C:\Program Files\Java\jdk-17"`
+        * For more detailed information, please refer to the following stackoverflow discussions:
+
+            * [Android Studio no option to change Gradle JDK path](https://stackoverflow.com/questions/75671906/)
+            * [Android Gradle plugin requires Java 11 to run. You are currently using Java 1.8, but i'm using java 11](https://stackoverflow.com/questions/71532385)
 
-    * Example of a successful result: `Setting "jdk-dir" value to "C:\Program Files\Java\jdk-17". You may need to restart any open editors for them to read new settings.`
+* Run in `PowerShell` with administrator rights: `flutter doctor --android-licenses` (we agree to all license terms)
 
-* For more detailed information, please refer to the following `stackoverflow` discussions:
-
-  * [stackoverflow - Android Studio no option to change Gradle JDK path](https://stackoverflow.com/questions/75671906/android-studio-no-option-to-change-gradle-jdk-path)
-
-  * [stackoverflow - Android Gradle plugin requires Java 11 to run. You are currently using Java 1.8, but i'm using java 11](https://stackoverflow.com/questions/71532385/android-gradle-plugin-requires-java-11-to-run-you-are-currently-using-java-1-8/72903843#72903843)
+* Run in `PowerShell` with administrator rights: `flutter doctor` - and make sure that all tests pass successfully (status: No issues found!)

docs/development/android_notes.md → docs/development/android_development.md

@@ -1,4 +1,4 @@
-# Android notes
+# Android development
 
 ## Kotlin and gradle versions
 
@@ -22,7 +22,25 @@ Related packages that must be compatible with each other and updated together:
 | `org.jetbrains.kotlin:kotlin-stdlib`        | `android/app/build.gradle` |
 | `androidx.*-ktx`                            | `android/app/build.gradle` |
 
-## Capturing device logs
+## Setup emulator on Windows
+
+Here is how you can setup Android emulator using Android Studio:
+
+* Open Android studio and navigate to `AVD Manager` (`Tools/AVD Manager`)
+
+* You can use `AVD Manager` to examine all your Android emulators.
+
+* Click the `+ Create Virtual Device...` button to add a new Android emulator.
+
+    * Select the desired device definition and click `Next`.
+    * Select the desired system image and click `Next`.
+    * Select the desired AVD device name and click `Finish`.
+
+* Go to your IDE (in our example we will use `Visual Studio Code`) and click `Select device to use` (usually in the bottom right corner of `Visual Studio Code`). Select the new Android emulator device from the list that opens and check that it boots and works without errors.
+
+* Click `Run/Start Debugging` in the IDE while the Android emulator device is active to verify that the application opens and runs correctly on the new AVD.
+
+## Capture device logs
 
 This script is a wrapper for `adb logcat`:
 
@@ -32,4 +50,4 @@ python3 ./script/android_logcat.py
 
 It filters out irrelevant logs and adds nice formatting and colorization (each log tag is assigned its own color).
 
-Unlike `flutter run`, you can launch it before the app when you need logs from the very early stages of initialization.
+Unlike `flutter run`, you can launch it before the app when you need logs from the very early stages of initialization. It also displays some additional logs and hides some unnecessary ones.

docs/development/automation.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-Commands below need Python3 and [doit](https://pydoit.org/) automation tool.
+Commands below need Python3 and [doit](https://pydoit.org/) automation tool. Targets are defined in `dodo.py` file.
 
 All commands are called from the root directory (using terminal).
 

docs/development/testing.md

@@ -1,34 +1,19 @@
 # Testing
 
-## General information about testing
+## Running tests
 
-* It is important to test the application on real devices, but for convenience, emulators are widely used for development and testing purposes. Here you can find documentation on how to set up such emulators:
+To run tests, see [Automation](./automation.md).
 
-  * [Emulator Setup Documentation](./emulator.md)
+To setup Android emulator and capture its logs, see [Android development](./android_development.md).
 
-## UI tests
+## Widget tests
 
-* If possible, all classes of roc-droid `UI` should be tested
+* When possible, UI classes (`lib/src/ui`) should be tested using Flutter widget testing (`testWidgets()` function).
 
-* The type of testing used for the `UI` is defined by `Flutter` as widget testing.
+* Documentation: <https://docs.flutter.dev/cookbook/testing/widget/introduction>
 
-* The `UI` should be tested based on the `Flutter` `testWidgets()` functionality.
+## Unit tests
 
-* Widget testing is described in the `Flutter` documentation here: <https://docs.flutter.dev/cookbook/testing/widget/introduction>
-
-## Model tests
-
-* If possible, all classes of roc-droid `Model` should be tested
-
-* The type of testing used for the `Model` is defined by `Flutter` as unit testing.
-
-* The `Model` should be tested based on the `Dart` `test()` functionality.
-
-* Unit testing is described in the `Flutter` documentation here: <https://docs.flutter.dev/cookbook/testing/unit/introduction>
-
-## Agent tests
-
-* If possible, all classes of roc-droid `Agent` should be tested
-
-TODO - add Agent unit testing description
+* When possible, non-UI classes (`lib/src/model`, `lib/src/agent`) should be covered with unit tests (`test()` function)
 
+* Documentation: <https://docs.flutter.dev/cookbook/testing/unit/introduction>

mkdocs.yml

@@ -24,8 +24,8 @@ nav:
   - Development:
     - Automation: development/automation.md
     - Testing: development/testing.md
+    - Android development: development/android_development.md
     - Release management: development/release_management.md
-    - Android notes: development/android_notes.md
 
 exclude_docs: |
   /screenshots