New documentation

2022-10-09 22:20:15 +02:00
parent 5c51926062
commit fc21a45f2f
95 changed files with 23605 additions and 198 deletions
@@ -0,0 +1 @@
+label: Developer Guide
@@ -0,0 +1,2 @@
+label: External APIs
+position: 2
@@ -0,0 +1,9 @@
+# Currency Exchange Rates
+
+Currency exchange rates are fetched from the following API endpoint:
+
+```
+https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml
+```
+
+This endpoint does not require any authentication, thus no configuration is required in order to enable the currency conversion feature in the unit converter.
@@ -0,0 +1,24 @@
+# Google Cloud Services
+
+Google Cloud Services are used for Google Drive search. To enable Google Drive integration in your builds, follow these steps:
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com)
+1. Create a new project.
+1. Enable the Drive API:
+   1. Go to APIs & Services > Library and search for the Google Drive API.
+   1. Enable this API for your project.
+1. Setup your OAuth consent screen
+   1. Go to APIs & Services > OAuth consent screen
+   1. On the Oauth consent screen page, fill out all the required fields
+   1. On the Scopes page, click add or remove scopes and add the following scopes: `userinfo.profile` and `drive.metadata.readonly`
+1. Create a new Oauth 2.0 client (you need to do this twice, for debug builds and for release builds)
+   1. Go to APIs & Services > Credentials
+   1. Click on Create Credentials > OAuth client ID
+   1. Choose application type Android
+   1. Enter the package name (`de.mm20.launcher2.debug` for debug builds or `de.mm20.launcher2.release` for release builds)
+   1. Enter the SHA-1 certificate fingerprint of your APK signing key
+   1. Click on create
+1. Download the client config file (repeat this step for both the debug and the release client)
+   1. On the APIs & Services > Credentials page, find your OAuth client in the list under OAuth 2.0 Client IDs.
+   1. Click on the download icon to download a `client_config.json`
+   1. Place this file under `g-services/src/debug/res/raw/g_services.json` or `g-services/src/release/res/raw/g_services.json`
@@ -0,0 +1,7 @@
+# External APIs
+
+Kvæsitso integrates with a number of external APIs. Most of them require some sort of authentication, like an API key. These API keys are not part of the GitHub repository. If you want to build Kvæsitso from source with all features enabled, follow the steps in this chapter.
+
+:::info
+Kvæsitso is still buildable even without these steps, but some features will be disabled in the resulting APK. If all you need is a debug build for testing purposes, you can probably skip this chapter.
+:::
@@ -0,0 +1,30 @@
+# Microsoft Graph Services
+
+Microsoft Graph Services are used for OneDrive search. To enable OneDrive integration in your builds, follow these steps:
+
+1. Go to the [Microsoft Azure Portal](https://portal.azure.com)
+1. Create a new project.
+   1. Search for App Registrations
+   1. Add a new registration
+      1. Supported account types: Accounts in any organizational directory and personal Microsoft accounts
+1. Add an authentication platform
+   1. Go to Authentication
+   1. Add a platform > Android
+   1. Enter the debug package name (de.mm20.launcher2.debug) and the signature hash of your debug key
+      1. You can use the following command to generate the signature hash:
+         `keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore | openssl sha1 -binary | openssl base64`
+   1. Click Configure > Done
+   1. In the newly created Android section, click on Add URI
+   1. Add package name (de.mm20.launcher2.release) and signature hash of your release key
+1. Download the client details
+   1. In the debug client row, click on View
+   1. Copy the JSON below MSAL Configuration to `ms-services/src/debug/res/raw/msal_auth_config.json` (you'll need to create this file first)
+1. Repeat the previous step for the release config
+1. Add the required scopes
+   1. Go to API permissions
+   1. Add a permission
+   1. Select Microsoft Graph > Delegated permissions
+   1. Tick the following scopes:
+      - Files.Read.All
+      - User.Read
+   1. Click Add permissions
@@ -0,0 +1,51 @@
+# Weather Services
+
+1. Copy the `weather/src/main/res/values/config_example.xml` to `weather/src/main/res/values/config.xml`
+
+#### OpenWeatherMap
+
+OpenWeatherMap offers 1 000 000 free API calls per month. However forecasts are only available for
+the next 5 days and only every 3 hours. Also note that each weather update uses two API calls (
+current weather + forecast).
+
+1. Register at [OpenWeatherMap](https://openweathermap.org/)
+1. Navigate to your user profile > API keys
+1. Create a new API key
+1. Uncomment the resource `openweather_key` in config.xml and paste your key as value.
+
+#### HERE
+
+HERE offers 250 000 free API calls per month. Each weather update uses one call.
+
+1. Sign up at the [HERE developer portal](https://developer.here.com/)
+1. Create a new project.
+1. Go to project details and under JavaScript, create a new API key.
+1. Uncomment the resource `here_key` in config.xml and paste your key as value.
+
+#### Meteorologisk institutt[^1]
+
+The Norwegian Meteorological Institute offers a free weather API. It has a rate limit of 20
+requests/s. You do not need an API key, however they require an
+identification and contact data to be present in the User Agent header in each request. Read the exact rules in their
+[Terms of Service](https://api.met.no/doc/TermsOfService).
+
+1. Uncomment `metno_contact` in config.xml. Fill in your contact data (an email address or a website
+   where your contact data can be found). This will be sent in the User Agent header, which will be
+   composed like
+   this:
+   ```
+    User-Agent: "{app package name}/signature:{app siganture hash} {@string/metno_contact}"
+   ```
+
+#### Bright Sky / Deutscher Wetterdienst[^1]
+
+Bright Sky is an API that converts data published by the Deutscher Wetterdienst to an easier
+to work with JSON format. The API is free to use and requires no additional configuration, however
+it only provides weather data for locations in Germany.
+
+[^1]:
+    These weather providers do not provide any means of geocoding or location lookup. Instead, the
+    Android Geocoder API is used to lookup locations (in fixed location mode) and location names (in
+    auto location mode). While most devices ship a Geocoder as part of the Google Play service, some
+    might not have a Geocoder installed. In these cases, this provider might not work properly (no
+    support for fixed locations and lat/lon values will be displayed instead of location names).
@@ -0,0 +1,3 @@
+# Wikipedia
+
+Kvæsitso uses the [Mediawiki API](https://www.mediawiki.org/wiki/API:Main_page) to load data from Wikipedia. No further configuration is required. The default Mediawiki installation URL is language-dependend and can be configured with `wikipedia_url` string resource in the `:i18n` module.
@@ -0,0 +1,7 @@
+---
+sidebar_position: 0
+---
+
+# Developer Guide
+
+You want to build Kvæsitso from source? Fix some bugs, develop new features or simply explore Kvæsitso's source code? Read this guide to learn how to setup the build environment and source code and to learn about the structure and organization of the source code.
@@ -0,0 +1,16 @@
+---
+sidebar_position: 4
+---
+
+# Libraries
+
+The following libraries are commonly used (libraries that are only used in single modules are not listed here as they are implementation details):
+
+- **KotlinX coroutines** for asynchronous operations
+- **Jetpack Compose and Accompanist** for all user interfaces _(TODO: Owncloud and Nextcloud signin are not ported to Compose yet)_
+- **AndroidX Room** to store launcher data in an Sqlite database
+- **AndroidX Protobuf Datastore** to store additional user preferences
+- **Koin** for dependency injection
+- **Coil** to load and transform images
+- **OkHttp and Retrofit** for HTTP requests
+- Several other **AndroidX** libraries (Work, Lifecycle, AppCompat, …)
@@ -0,0 +1,47 @@
+---
+sidebar_position: 3
+---
+
+# Modules
+
+The source code consists of a number of Gradle submodules which all depend on each other in some way or another:
+
+- `:accounts`: Common APIs to manage different account types (Google, Microsoft, Nextcloud, …)
+- `:app`: The app module. Contains almost nothing except for the `Application` class (`de.mm20.launcher2.LauncherApplication`)
+- `:applications`: Installed apps and app search
+- `:appshortcuts`: Query apps shortcuts for apps and shortcut search
+- `:backup`: Backup and restore functionality
+- `:badges`: Provide different types of badges that are displayed on app icons
+- `:base`: Commonly used data classes, helper functions and utilities. Also icon resources (if they do not need localization).
+- `:calculator`: Implements the calculator
+- `:calendar`: query calendar events for the calendar widget and calendar search
+- `:compat`: Compatibility helpers for old Android versions
+- `:contacts`: Contact search
+- `:crashreporter`: Crash reporter; based on https://github.com/MindorksOpenSource/CrashReporter
+- `:currencies`: APIs to fetch currency conversion rates, used by `:unitconverter`
+- `:customattrs`: common (low-level) APIs to store per-app customizations (custom labels, custom icons, tags)
+- `:database`: the launcher database, uses AndroidX Room
+- `:favorites`: Handles pinned, frequently used and hidden items and serialization / deserialization of items. Depends on most of the search modules (`:apps`, `:calendar`, `:contacts`, etc.)
+- `:files`: File search (local and cloud)
+- `:g-services`: Google APIs and Google sign-in; used by `:accounts` and `:files`
+- `:i18n`: All resources that require localization. Mainly strings but can also be used for icon resources if they need localization.
+- `:icons`: Used to retrieve icons for items. Handles icon packs, themed icons and also custom icons (on a higher level)
+- `:ktx`: Commonly used Kotlin extension functions
+- `:material-color-utilities`: This library: https://github.com/material-foundation/material-color-utilities (not available as Gradle package yet)
+- `:ms-services`: Microsoft APIs and Microsoft sign-in; used by `:accounts` and `:files`
+- `:music`: Manage media sessions and extract metadata
+- `:nextcloud`: Nextcloud APIs and Nextcloud sign-in; used by `:accounts` and `:files`
+- `:notifications`: APIs to read notifications. Contains the app's `NotificationListenerService`
+- `:owncloud`: Owncloud APIs and Owncloud sign-in; used by `:accounts` and `:files`
+- `:permissions`: Request and observe permission status for this app
+- `:preferences`: Store user preferences; uses AndroidX Datastore
+- `:search`: Base classes for search items and search item serialization. Also websearches. Does not contain the actual search which is split across several modules (`:applications`, `:calendar`, `:contacts`, `:files` and so on)
+- `:ui`: Contains almost the entire user interface (except for account sign-in UIs). Uses Jetpack Compose.
+- `:unitconverter`: Unit and currency converter
+- `:weather`: APIs to fetch weather data
+- `:webdav`: common APIs for WebDAV search, used by `:nextcloud` and `:owncloud`
+- `:websites`: Website search
+- `:widgets`: Manages configuration of widgets (which widgets and which order). Actual widget implementation (for built-in widgets) is in `:ui`.
+- `:wikipedia`: APIs to search Wikipedia
+
+Most of the modules have a `Module.kt` file in their root which contains Koin definitions to make the APIs accessable for other modules.
@@ -0,0 +1,11 @@
+---
+sidebar_position: 1
+---
+
+# Setup
+
+## Setup the build environment
+
+- Download and install the latest canary version of Android Studio and the Android SDK: https://developer.android.com/studio/preview.
+- Clone the Git repository: `git clone https://github.com/MM2-0/Kvaesitso`
+- Open the project in Android Studio