Adjust documentation for mkdocs

- add mkdocs.yml - change folder structure in docs/: architecture/, development/, _diagrams/, _screenshots/ - source code links converted to absolute links - naked links converted to <links>
gavv · Oct 10, 2024 · 167b562 · 167b562
1 parent 478ee5c
commit 167b562
Show file tree

Hide file tree

Showing 22 changed files with 81 additions and 105 deletions.
diff --git a/docs/diagrams/architecture.drawio → docs/_diagrams/architecture.drawio b/docs/diagrams/architecture.drawio → docs/_diagrams/architecture.drawio
diff --git a/docs/images/architecture.png → docs/_diagrams/architecture.png b/docs/images/architecture.png → docs/_diagrams/architecture.png
diff --git a/docs/diagrams/model.drawio → docs/_diagrams/model.drawio b/docs/diagrams/model.drawio → docs/_diagrams/model.drawio
diff --git a/docs/images/model.png → docs/_diagrams/model.png b/docs/images/model.png → docs/_diagrams/model.png
diff --git a/docs/diagrams/widget_tree.drawio → docs/_diagrams/widget_tree.drawio b/docs/diagrams/widget_tree.drawio → docs/_diagrams/widget_tree.drawio
diff --git a/docs/images/widget_tree.png → docs/_diagrams/widget_tree.png b/docs/images/widget_tree.png → docs/_diagrams/widget_tree.png
diff --git a/docs/diagrams/widget_types.drawio → docs/_diagrams/widget_types.drawio b/docs/diagrams/widget_types.drawio → docs/_diagrams/widget_types.drawio
diff --git a/docs/images/widget_types.png → docs/_diagrams/widget_types.png b/docs/images/widget_types.png → docs/_diagrams/widget_types.png
diff --git a/docs/screenshots/screenshot.webp → docs/_screenshots/screenshot.webp b/docs/screenshots/screenshot.webp → docs/_screenshots/screenshot.webp
diff --git a/docs/architecture/agent.md b/docs/architecture/agent.md
@@ -0,0 +1,3 @@
+# Agent
+
+TODO - add a description of the agent module when it becomes clear
diff --git a/docs/architecture_model.md → docs/architecture/model.md b/docs/architecture_model.md → docs/architecture/model.md
@@ -1,36 +1,31 @@
-# Model architecture
-
-**Table of contents:**
-
-- [Model architecture description](#model-architecture-description)
-  - [Model tree](#model-tree)
+# Model
 
 ## Model tree
 
-![](/docs/images/model.png)
+![](/_diagrams/model.png)
 
 The roc-droid `Model` module is responsible for managing the data model of the application's graphical interface. Data changes in the model are initiated by the `Agent` module and then utilized by the `UI` module.
 
 Description of the model tree:
 
 * The roc-droid client application's model is based on the `ModelRoot` class, highlighted in violet.
 
-  * Class implementation: [ModelRoot](/lib/src/model/model_root.dart)
+  * Class implementation: [ModelRoot](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/model/model_root.dart)
 
 * The `ModelRoot` class itself is derived from two base classes: `Receiver` and `Sender`, both highlighted in red.
 
   * The red classes contain `@observable`, `@computed` fields and `@action` methods provided in the `Mobx` package.
 
-  * Receiver implementation: [Receiver](/lib/src/model/receiver.dart)
+  * Receiver implementation: [Receiver](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/model/receiver.dart)
 
-    * The Receiver has its own automatically generated code for the correct operation of `Mobx`: [receiver.g.dart](/lib/src/model/receiver.g.dart)
+    * The Receiver has its own automatically generated code for the correct operation of `Mobx`: [receiver.g.dart](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/model/receiver.g.dart)
 
-  * Sender implementation: [Sender](/lib/src/model/sender.dart)
+  * Sender implementation: [Sender](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/model/sender.dart)
 
-    * The Sender has its own automatically generated code for the correct operation of `Mobx`: [sender.g.dart](/lib/src/model/sender.g.dart)
+    * The Sender has its own automatically generated code for the correct operation of `Mobx`: [sender.g.dart](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/model/sender.g.dart)
 
 * The `Logger` class is managed by the Flutter `logger` package and is highlighted in yellow.
 
 * The `CaptureSourceType` enumerator control the type of capture source and is colored gray.
 
-  * enum implementation: [CaptureSourceType](/lib/src/model/capture_source_type.dart)
+  * enum implementation: [CaptureSourceType](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/model/capture_source_type.dart)
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
@@ -0,0 +1,13 @@
+# Overview
+
+![](/_diagrams/architecture.png)
+
+roc-droid is responsible for implementing and managing the functionality of the roc-toolkit logic in the form of an application.
+
+The roc-droid implementation is comprised of three modules:
+
+* [**UI**](/architecture/ui) – (`lib/src/ui`): This module is responsible for rendering the user interface and handling user interactions with the application functionality.
+
+* [**Model**](/architecture/model) – (`lib/src/model`): This module contains all the primary classes and entities necessary for updating the visual display of the graphical interface.
+
+* [**Agent**](/architecture/agent) – (`lib/src/agent`): This module manages client interaction with the core logic of the roc-toolkit.
diff --git a/docs/architecture_ui.md → docs/architecture/ui.md b/docs/architecture_ui.md → docs/architecture/ui.md
@@ -1,14 +1,8 @@
-# User interface architecture
-
-**Table of contents:**
-
-- [User interface architecture description](#user-interface-architecture-description)
-  - [Widget types](#widget-types)
-  - [Widget tree](#widget-tree)
+# User interface
 
 ## Widget types
 
-![](/docs/images/widget_types.png)
+![](/_diagrams/widget_types.png)
 
 Widgets can be categorized into the following types:
 
@@ -48,7 +42,7 @@ Widgets can be categorized into the following types:
 
 ## Widget tree
 
-![](/docs/images/widget_tree.png)
+![](/_diagrams/widget_tree.png)
 
 The UI diagram of the Rock Droid application client illustrates a tree of widgets that form the visual presentation for the user.
 
@@ -58,29 +52,29 @@ Designations:
 
   * roc-droid classes:
 
-    * [AppRoot](/lib/src/ui/app_root.dart)
+    * [AppRoot](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/ui/app_root.dart)
 
 * **Red:** Screen-level widgets (`Content Layer`)
 
   * roc-droid classes:
 
-    * [MainScreen](/lib/src/ui/main_screen.dart)
+    * [MainScreen](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/ui/main_screen.dart)
 
 * **Orange:** Page-level widgets (`Content Layer`)
 
   * roc-droid classes:
 
-    * [ReceiverPage](/lib/src/ui/pages/receiver_page.dart)
+    * [ReceiverPage](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/ui/pages/receiver_page.dart)
 
-    * [SenderPage](/lib/src/ui/pages/sender_page.dart)
+    * [SenderPage](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/ui/pages/sender_page.dart)
 
-    * [AboutPage](/lib/src/ui/pages/about_page.dart)
+    * [AboutPage](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/ui/pages/about_page.dart)
 
 * **Yellow:** Fragment-level widgets (`Content Layer`)
 
   * roc-droid classes:
 
-    * [RocBottomNavigationBar](/lib/src/ui/fragments/roc_bottom_navigation_bar.dart)
+    * [RocBottomNavigationBar](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/ui/fragments/roc_bottom_navigation_bar.dart)
 
 * **Gray:** Native Flutter `Widget` class (`Representation Layer`)
 
@@ -92,18 +86,18 @@ Designations:
 
       * Representing Widgets that provide certain data to the user.
 
-        * [RocChip](/lib/src/ui/components/roc_chip.dart)
+        * [RocChip](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/ui/components/roc_chip.dart)
 
-        * [RocTextRow](/lib/src/ui/components/roc_text_row.dart)
+        * [RocTextRow](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/ui/components/roc_text_row.dart)
 
       * Representing Widgets that provide the user with the ability to enter certain data.
 
-        * [RocDropdownButton](/lib/src/ui/components/roc_dropdown_button.dart)
+        * [RocDropdownButton](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/ui/components/roc_dropdown_button.dart)
 
-        * [RocStatefulButton](/lib/src/ui/components/roc_stateful_button.dart)
+        * [RocStatefulButton](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/ui/components/roc_stateful_button.dart)
 
       * Representing Widgets that control specific view representations.
 
-        * [RocPageView](/lib/src/ui/components/roc_page_view.dart)
+        * [RocPageView](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/ui/components/roc_page_view.dart)
 
-        * [RocScrollView](/lib/src/ui/components/roc_scroll_view.dart)
+        * [RocScrollView](https://github.com/roc-streaming/roc-droid/tree/main/lib/src/ui/components/roc_scroll_view.dart)
diff --git a/docs/architecture_agent.md b/docs/architecture_agent.md
diff --git a/docs/architecture_overview.md b/docs/architecture_overview.md
diff --git a/docs/development.md → docs/development/android_notes.md b/docs/development.md → docs/development/android_notes.md
@@ -1,4 +1,4 @@
-# Development
+# Android notes
 
 ## Kotlin and gradle versions
 
@@ -22,7 +22,7 @@ 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` |
 
-## Capture android logs
+## Capturing device logs
 
 This script is a wrapper for `adb logcat`:
 

diff --git a/docs/automation.md → docs/development/automation.md b/docs/automation.md → docs/development/automation.md
diff --git a/docs/release_management.md → docs/development/release_management.md b/docs/release_management.md → docs/development/release_management.md
diff --git a/docs/install_win.md → docs/development/setup_windows.md b/docs/install_win.md → docs/development/setup_windows.md
@@ -1,16 +1,8 @@
-# Flutter setup on Windows
-
-**Table of contents:**
-
-- [Flutter setup on Windows:](#flutter-setup-on-windows)
-  - [Choco installation (optional, but recommended)](#choco-installation-optional-but-recommended)
-  - [Flutter installation](#flutter-installation)
-  - [Android Studio installation](#android-studio-installation)
-  - [Flutter setup](#flutter-setup)
+# Windows setup
 
 ## Choco installation (optional, but recommended)
 
-* Choco installation documentation: https://chocolatey.org/install
+* Choco installation documentation: <https://chocolatey.org/install>
 
 * Open `PowerShell` with administrator rights
 
@@ -29,17 +21,17 @@
 
 * Installing Flutter manually:
 
-    * Flutter SDK installation: https://flutter.dev/docs/get-started/install/windows
+    * 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
+    * Setting up a global environment for Windows: <https://flutter.dev/docs/get-started/install/windows#update-your-path>
 
 * For Flutter update use: `flutter upgrade`
 
 ## Android Studio installation
 
-* Installing Android studio: https://developer.android.com/studio#downloads
+* Installing Android studio: <https://developer.android.com/studio#downloads>
 
-* Installing Android SDK Command Line Tools from Android SDK Manager (copied and translated for Stack Overflow: https://stackoverflow.com/questions/64708446/flutter-doctor-android-licenses-Exception-in-thread-main-java-lang - no class):
+* Installing Android SDK Command Line Tools from Android SDK Manager ([adopted from Stack Overflow](https://stackoverflow.com/questions/64708446/)):
 
     * Open android studio
 
@@ -57,8 +49,8 @@
 
 ## Flutter setup
 
-* Run in `PowerShell` with administrator rights: flutter config --android-studio-dir="C:\Program Files\Android\Android Studio" (specify directory)
+* Run in `PowerShell` with administrator rights: `flutter config --android-studio-dir="C:\Program Files\Android\Android Studio"` (specify directory)
 
-* Run in `PowerShell` with administrator rights: flutter doctor --android-licenses (we agree to all license terms)
+* Run in `PowerShell` with administrator rights: `flutter doctor --android-licenses` (we agree to all license terms)
 
-* 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 doctor` - and make sure that all tests pass successfully (status: No issues found!)
diff --git a/docs/unit_tests.md → docs/development/testing.md b/docs/unit_tests.md → docs/development/testing.md
@@ -1,34 +1,26 @@
-# Unit testing description
+# Testing
 
-**Table of contents:**
-
-- [Unit testing description](#unit-testing-description)
-  - [UI unit testing](#ui-unit-testing)
-  - [Model unit testing](#model-unit-testing)
-  - [Agent unit testing](#agent-unit-testing)
-
-
-## UI unit testing
+## UI tests
 
 * If possible, all classes of roc-droid `UI` should be tested
 
 * The type of testing used for the `UI` is defined by `Flutter` as widget testing.
 
 * The `UI` should be tested based on the `Flutter` `testWidgets()` functionality.
 
-* Widget testing is described in the `Flutter` documentation here: https://docs.flutter.dev/cookbook/testing/widget/introduction
+* Widget testing is described in the `Flutter` documentation here: <https://docs.flutter.dev/cookbook/testing/widget/introduction>
 
-## Model unit testing
+## 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
+* Unit testing is described in the `Flutter` documentation here: <https://docs.flutter.dev/cookbook/testing/unit/introduction>
 
-## Agent unit testing
+## Agent tests
 
 * If possible, all classes of roc-droid `Agent` should be tested
 

diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,3 @@
+# Roc Droid
+
+Welcome to Roc Droid documentation!
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,22 @@
+site_name: Roc Droid documentation
+copyright: Copyright (c) Roc Streaming authors.
+
+repo_url: https://github.com/roc-streaming/roc-droid
+edit_uri: https://github.com/roc-streaming/roc-droid/edit/main/docs/
+
+theme:
+  name: readthedocs
+
+nav:
+  - Home: index.md
+  - Architecture:
+    - Overview: architecture/overview.md
+    - User interface: architecture/ui.md
+    - Model: architecture/model.md
+    - Agent: architecture/agent.md
+  - Development:
+    - Windows setup: development/setup_windows.md
+    - Automation: development/automation.md
+    - Testing: development/testing.md
+    - Release management: development/release_management.md
+    - Android notes: development/android_notes.md
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Agent

		TODO - add a description of the agent module when it becomes clear
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Roc Droid

		Welcome to Roc Droid documentation!