Initial MkDocs code

.github/workflows/deploy-wiki.yml

@@ -0,0 +1,32 @@
+name: Deploy MkDocs 
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'mkdocs.yml'
+      - 'wiki/**'
+      - '.github/workflows/deploy-wiki.yml'
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

README.md

@@ -7,7 +7,7 @@ Get Android app updates straight from the source.
 Obtainium allows you to install and update apps directly from their releases pages, and receive notifications when new releases are made available.
 
 More info:
-- [Obtainium Wiki](https://github.com/ImranR98/Obtainium/wiki)
+- [Obtainium Wiki](https://imranr98.github.io/Obtainium)
 - [AppVerifier](https://github.com/soupslurpr/AppVerifier) - App verification tool (recommended, integrates with Obtainium)
 - [apps.obtainium.imranr.dev](https://apps.obtainium.imranr.dev/) - Crowdsourced app configurations ([repository](https://github.com/ImranR98/apps.obtainium.imranr.dev))
 - [Side Of Burritos - You should use this instead of F-Droid | How to use app RSS feed](https://youtu.be/FFz57zNR_M0) - Original motivation for this app

fastlane/metadata/android/en-US/full_description.txt

@@ -1,5 +1,5 @@
 <p>Obtainium allows you to install and update Apps directly from their releases pages, and receive notifications when new releases are made available.</p>
-<p>Read the <a href="https://github.com/ImranR98/Obtainium/wiki">Wiki</a></p>
+<p>Read the <a href="https://imranr98.github.io/Obtainium">Wiki</a></p>
 <p>
 	<b>Currently supported App sources:</b>
 </p>

fastlane/metadata/android/ru/full_description.txt

@@ -1,5 +1,5 @@
 <p>Obtainium позволяет вам устанавливать и обновлять приложения прямо с их объявлений о выпусках и получать уведомления о новых выпусках.</p>
-<p>Для деталей читайте <a href="https://github.com/ImranR98/Obtainium/wiki">Вики</a></p>
+<p>Для деталей читайте <a href="https://imranr98.github.io/Obtainium">Вики</a></p>
 <p>
 	<b>Поддерживаемые источники приложений:</b>
 </p>

lib/pages/settings.dart

@@ -886,7 +886,7 @@ class _SettingsPageState extends State<SettingsPage> {
                     ),
                     IconButton(
                       onPressed: () {
-                        launchUrlString('${settingsProvider.sourceUrl}/wiki',
+                        launchUrlString(settingsProvider.wikiUrl,
                             mode: LaunchMode.externalApplication);
                       },
                       icon: const Icon(Icons.help_outline_rounded),

lib/providers/settings_provider.dart

@@ -31,6 +31,7 @@ class SettingsProvider with ChangeNotifier {
   bool justStarted = true;
 
   String sourceUrl = 'https://github.com/ImranR98/Obtainium';
+  String wikiUrl = 'https://imranr98.github.io/Obtainium';
 
   // Not done in constructor as we want to be able to await it
   Future<void> initializeSettings() async {

mkdocs.yml

@@ -0,0 +1,73 @@
+site_name: Obtainium Wiki
+repo_url: https://github.com/ImranR98/Obtainium
+docs_dir: wiki
+site_description: Help page for Obtainium
+site_author: ImranR98
+edit_uri: edit/main/wiki/
+
+nav:
+  - Home: index.md
+  - UI Overview: ui_overview.md
+  - How Apps are Tracked: app_tracking.md
+  - App Sources: sources.md
+  - Settings: settings.md
+
+theme:
+  name: material
+  logo: assets/logo.png
+  custom_dir: wiki/overrides
+  favicon: https://raw.githubusercontent.com/ImranR98/Obtainium/main/assets/graphics/icon_small.png
+
+  features:
+    - navigation.instant
+    - navigation.instant.progress
+    - content.action.edit
+    - search.suggest
+    - search.highlight
+    - search.share
+    - content.tooltips
+
+  icon:
+    repo: fontawesome/brands/github
+    annotation: material/arrow-right-circle
+
+  palette:
+    - primary: deep purple
+    - accent: green
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - attr_list
+  - md_in_html
+  - attr_list
+  - pymdownx.snippets
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.tabbed:
+      alternate_style: true
+
+extra:
+  social:
+    - icon: simple/github
+      link: https://github.com/ImranR98/
+      name: GitHub
+    - icon: simple/mastodon
+      link: https://freeradical.zone/@imran
+      name: Mastodon
+    - icon: simple/kofi
+      link: https://ko-fi.com/imranr
+      name: Ko-fi
+    - icon: material/heart
+      link: https://github.com/sponsors/ImranR98
+      name: GitHub Sponsors
+    - icon: material/web
+      link: https://imranr.dev/
+      name: Website
+
+plugins:
+  - search
+
+extra_css:
+  - stylesheets/custom.css

wiki/app_tracking.md

@@ -0,0 +1,79 @@
+---
+title: How Apps are Tracked
+description: How Apps are Tracked in Obtainium
+---
+
+# How Apps are Tracked
+
+## Basics
+
+When you add an app URL to Obtainium, you must pick an app [source](sources.md). Sources define how app info and APK files will be extracted from the URL you enter. Most of the time, Obtainium will automatically select the appropriate source to use - when this is not possible, an "Override Source" dropdown will be presented.
+
+At minimum, an app source must provide the following data for its apps:
+
+- The app version (or a 'pseudo-version' - an identifier that changes for each new version of the app)
+- At least one APK download URL that corresponds to the version that was provided
+
+App sources may also provide other info - these enable extra features or UI benefits. For example:
+
+- The app author's name
+- The app's package ID
+- The release date of the latest version
+- Info for previous versions or variants of the app
+
+In an ideal world, each app source would provide all required info in a straightforward way - with a single app per given URL with all required info provided in a standard format. However this is often not the case - there are many different ways app releases are handled even by the same source, so it isn't possible to have a fixed set of steps to handle them all. For this reason, you are presented with various additional options when adding an app, and these can be used to modify the way app info will be extracted. While the defaults work for most apps, you may want to understand these options to deal with edge cases - more info in the [App Sources](sources.md) section below.
+
+Note: Many filter settings in Obtainium (including many source-specific optional filters) make use of [regular expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) - you should be familiar with these.
+
+## Version Detection
+
+When Obtainium is tracking an app that is currently installed, it grabs the version of the app from Android and compares it to the version string provided by the source. It then compares the two to decide whether an update is available or whether the install status of the app has changed. This comparison can only be made if the two versions follow the same format, which may not always be the case. For example, you could have any of these cases among others:
+
+1. [Obtainium](https://github.com/ImranR98/Obtainium/releases/tag/v0.14.21-beta) from GitHub:
+   - Android-reported app version: `0.14.21`
+   - Source-reported version: `v0.14.21-beta` 
+2. [Cheogram](https://git.singpolyma.net/cheogram-android/refs/2.12.8-2) from a SourceHut instance:
+   - Android-reported app version: `2.12.8-2+free`
+   - Source-reported version: `2.12.8-2`
+3. [Tor](https://www.torproject.org/download/) from the Tor website:
+   - Android-reported app version: `102.2.1-Release (12.5.6)`
+   - Source-reported version: none (no version string is provided by this HTML source so a URL hash is used instead as a 'pseudo-version')
+4. [Quotable](https://github.com/Lijukay/Qwotable/releases/tag/v10) from GitHub:
+   - Android-reported app version: `1`
+   - Source-reported version: `v10` 
+
+Obtainium stores a list of "standard" formats which it uses to make this comparison (like `x.y.z` or `x.y`). If both versions being compared conform to the same format, the comparison will be made. If not, version detection will be disabled for that app. In some cases, Obtainium will strip off extra parts from the source string if doing so would result in a standard version (like how `v` and `-beta` are removed from Obtainium's `v0.14.21-beta`), then it can make the comparison. We never try to strip parts off the "real" OS-provided version.
+
+This piece of code defines how the various "standard" formats are generated: https://github.com/ImranR98/Obtainium/blob/main/lib/providers/apps_provider.dart#L64
+
+It's always possible to expand that code to add support for more formats, but this requires careful consideration. For example if Android reports that an installed app's version is `1.2` but the source says the latest available version of that app is `1.2-4`, should we strip off the `-4` and say the two are the same (meaning there is no update available)? This may be fine in some contexts (where the `-4` is not actually indicative of a change in the app itself) but not in other contexts. So it wouldn't be a good idea to support that specific case.
+
+Version detection being turned off should not usually have a significant impact on day-to-day use. If version detection is disabled for an app, you may occasionally run into inconsistencies between the real version of the app installed on your system and the version shown in the Obtainium UI. This should only happen in two cases:
+
+1. If an app's version changes due to actions taken outside of Obtainium (for example if it gets updated by Google Play)
+2. If an attempt by Obtainium to [silently update](#background-updates) the app in the background fails
+
+In such cases, Obtainium would not be able to detect that the app's real OS version has changed and so it would not update its internal records accordingly - you would need to manually correct the inconsistency.
+
+See also: https://github.com/ImranR98/Obtainium/issues/946#issuecomment-1741745587
+
+## Background Updates
+
+Obtainium checks for app updates in the background on a regular basis. You can control the frequency of these update tasks on the settings page.
+
+After a background update checking task is completed, any available updates are divided into 2 categories:
+
+1. Updates that can be applied in the background
+2. Updates that cannot be applied in the background
+
+For an update to be automatically installed in the background (AKA a silent update), certain criteria should be met:
+
+- The OS must be Android 12 or higher
+- The app being installed must target a [recent Android API level](https://developer.android.com/reference/android/content/pm/PackageInstaller.SessionParams#setRequireUserAction(int))
+- The currently installed version of the app must have been installed by Obtainium
+- You must have background updates enabled in Obtainium (both universally and for this app in particular - this is the default)
+- If there are multiple APKs available for the update, the additional options for that app must be configured such that Obtainium can filter these down to one APK
+
+Each available update is downloaded and installed if possible, and the user is then notified either of the update's availability or that it was installed in the background.
+
+Note that due to technical limitations, background updates can only be installed on an asynchronous, best-effort basis. So if a background update fails to install, you will not be notified of the error.

wiki/index.md

@@ -0,0 +1,71 @@
+# ![Obtainium Icon](https://raw.githubusercontent.com/ImranR98/Obtainium/main/assets/graphics/icon_small.png) Obtainium Wiki
+
+---
+
+[![Ceasefire Now](https://badge.techforpalestine.org/default)](https://techforpalestine.org/learn-more)
+
+Get Android app updates straight from the source.
+
+Obtainium's core goal is to automate the process of downloading and installing Android app updates directly from their "source" websites (sites where app files are available for direct download). This process needs automation since users may not be willing or able to rely on an app store to update a given app, but Android apps (unlike PC apps) usually assume they will be updated externally by an app store and therefore don't include a built-in self-update function.
+
+While this concept is simple, the wide variety of supported sources, user preferences, and APK naming, versioning, and distribution methods make things more complicated. This Wiki explains the various app sources and settings available in Obtainium. It is not comprehensive and may not be fully up to date.
+
+More info
+
+- [AppVerifier](https://github.com/soupslurpr/AppVerifier) - App verification tool (recommended, integrates with Obtainium)
+- [apps.obtainium.imranr.dev](https://apps.obtainium.imranr.dev/) - Crowdsourced app configurations
+- [Side Of Burritos - You should use this instead of F-Droid | How to use app RSS feed](https://youtu.be/FFz57zNR_M0) - Original motivation for this app
+
+Currently supported App sources:
+
+- Open Source - General:
+    - [GitHub](https://github.com/)
+    - [GitLab](https://gitlab.com/)
+    - [Forgejo](https://forgejo.org/) ([Codeberg](https://codeberg.org/))
+    - [F-Droid](https://f-droid.org/)
+    - Third Party F-Droid Repos
+    - [IzzyOnDroid](https://android.izzysoft.de/)
+    - [SourceHut](https://git.sr.ht/)
+- Other - General:
+    - [APKPure](https://apkpure.net/)
+    - [Aptoide](https://aptoide.com/)
+    - [Uptodown](https://uptodown.com/)
+    - [Huawei AppGallery](https://appgallery.huawei.com/)
+    - [Tencent App Store](https://sj.qq.com/)
+    - Jenkins Jobs
+    - [APKMirror](https://apkmirror.com/) (Track-Only)
+- Open Source - App-Specific:
+    - [VLC](https://videolan.org/)
+- Other - App-Specific:
+    - [WhatsApp](https://whatsapp.com)
+    - [Telegram App](https://telegram.org)
+    - [Neutron Code](https://neutroncode.com)
+- Direct APK Link
+- "HTML" (Fallback): Any other URL that returns an HTML page with links to APK files
+
+## Finding App Configurations
+
+You can find crowdsourced app configurations at [apps.obtainium.imranr.dev](https://apps.obtainium.imranr.dev).
+
+If you can't find the configuration for an app you want, feel free to leave a request on the [discussions page](https://github.com/ImranR98/apps.obtainium.imranr.dev/discussions/new?category=app-requests).
+
+Or, contribute some configurations to the website by creating a PR at [this repo](https://github.com/ImranR98/apps.obtainium.imranr.dev).
+
+## Installation
+
+[<img src="https://github.com/machiav3lli/oandbackupx/raw/034b226cea5c1b30eb4f6a6f313e4dadcbb0ece4/badge_github.png"
+    alt="Get it on GitHub">](https://github.com/ImranR98/Obtainium/releases)
+[<img src="https://gitlab.com/IzzyOnDroid/repo/-/raw/master/assets/IzzyOnDroid.png"
+     alt="Get it on IzzyOnDroid">](https://apt.izzysoft.de/fdroid/index/apk/dev.imranr.obtainium)
+[<img src="https://fdroid.gitlab.io/artwork/badge/get-it-on.png"
+    alt="Get it on F-Droid">](https://f-droid.org/packages/dev.imranr.obtainium.fdroid/)
+
+Verification info:
+
+- Package ID: `dev.imranr.obtainium`
+- SHA-256 Hash of Signing Certificate: `B3:53:60:1F:6A:1D:5F:D6:60:3A:E2:F5:0B:E8:0C:F3:01:36:7B:86:B6:AB:8B:1F:66:24:3D:A9:6C:D5:73:62`
+  - Note: The above signature is also valid for the F-Droid flavour of Obtainium, thanks to [reproducible builds](https://f-droid.org/docs/Reproducible_Builds/).
+- [PGP Public Key](https://keyserver.ubuntu.com/pks/lookup?search=contact%40imranr.dev&fingerprint=on&op=index) (to verify APK hashes)
+
+## Limitations
+- For some sources, data is gathered using Web scraping and can easily break due to changes in website design. In such cases, more reliable methods may be unavailable.

wiki/overrides/partials/copyright.html

@@ -0,0 +1,14 @@
+<div class="md-copyright">
+    <div class="md-copyright__inner">
+      <span class="md-copyright__item">Made by <a href="https://github.com/ImranR98" class="md-copyright__link">ImranR98</a></span>
+      <span class="md-copyright__separator">•</span>
+      <span class="md-copyright__item"><a href="https://github.com/ImranR98/Obtainium/issues/new/choose" class="md-copyright__link">Open an Issue</a></span>
+      <span class="md-copyright__separator">•</span>
+      <span class="md-copyright__item"><a href="https://apps.obtainium.imranr.dev/" class="md-copyright__link">Crowdsourced App Configurations</a></span>
+      <span class="md-copyright__separator">•</span>
+      <span class="md-copyright__item"><a href="https://obtainium.imranr.dev/" class="md-copyright__link">Obtainium Website</a></span>
+    </div>
+    <div class="md-copyright__material">
+      Made with <a href="https://squidfunk.github.io/mkdocs-material/">Material for MkDocs</a>
+    </div>
+  </div>

wiki/settings.md

@@ -0,0 +1,51 @@
+---
+title: Settings
+description: Settings explained
+---
+
+# Settings
+
+Explainations of the options in Obtainium Settings
+
+## Source Specific
+
+GitHub puts a cap on the number of API requests you can make in a given period of time. Since Obtainium uses the GitHub API to grab release info, you may run into a "rate limit" error if you have more than a few dozen GitHub apps. You can get around this by getting a Personal Access Token.
+
+GitLab releases sometimes contain APKs that are attached in non-standard ways, such that Obtainium cannot get to them easily. The GitLab API provides a far more reliable way to extract APKs but it cannot be used without an API key. While this shouldn't be an issue for most GitLab repos, you can add your own Personal Access Token in Obtainium's settings for more reliable APK extraction in edge cases where it does turn out to be a problem.
+
+### Setting Up Personal Access Tokens
+
+=== ":simple-github: GitHub"
+    To avoid API rate limits when tracking GitHub apps:
+
+    1. Login to [GitHub](https://github.com).
+
+    2. Go to the [Fine-grained tokens](https://github.com/settings/tokens?type=beta) section in developer settings.
+
+    3. Select **Generate new token**.
+
+    4. Give your token name and set an expiry date.
+
+    5. Scroll to the bottom and select **Generate token**.
+
+    6. Copy the token and paste it into the Obtainium settings. Make sure to copy your token now as you will not be able to see it again.
+
+=== ":simple-gitlab: GitLab"
+    For more reliable APK extraction from GitLab releases:
+
+    1. Login to [GitLab](https://github.com).
+
+    2. Go to the [personal access tokens](https://gitlab.com/-/user_settings/personal_access_tokens) section in settings.
+
+    3. Select **Add new token**.
+
+    4. Give your token name and set an expiration date.
+
+    5. Tick the `read_api` box.
+
+    6. Scroll to the bottom and select **Create personal access token**.
+
+    7. Copy the token and paste it into the Obtainium settings. Make sure to copy your token now as you will not be able to see it again.
+
+    !!! info "When is this needed?"
+        See [this explanation](https://github.com/ImranR98/Obtainium/issues/3#issuecomment-1234695412) about non-standard APK attachments in GitLab releases