kiwix/kiwix-android-custom
1
0
Fork 0
mirror of https://github.com/kiwix/kiwix-android-custom.git synced 2025-09-22 11:35:36 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #48 from kiwix/readme-improvements

Browse Source 
Readme improvements
This commit is contained in:
Kelson 2019-12-06 10:31:15 +01:00 committed by GitHub
commit efae07f71d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 144 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

199
README.md
View File

@ -1,94 +1,171 @@
# kiwix-android-custom
Overview
This project contains a python script and various folders containing information needed to create specific custom Kiwix Android apps.
_It does *not* create the app_, that's done separately by running the relevant Gradle command to build one or more custom apps.
# Kiwix Android custom apps
The script runs with Python 3. It also requires imagemagick be installed.
Kiwix Android custom apps are Android apps running [Kiwix for
Android](https://github.com/kiwix/kiwix-android) ZIM reader against a
pre-configured ZIM file.
## Installing the prerequisites
Android studio is required to generate icon sets and can be downloaded from [here](https://developer.android.com/studio/?gclid=Cj0KCQiAiNnuBRD3ARIsAM8KmlvCImKxWu_AGECa8YM5pM7Nr_algyHXSkfbPRTio3WEeKTaEfFiFeIaAs81EALw_wcB)
Kiwix publishes more than [a dozen of such apps](https://play.google.com/store/apps/collection/cluster?clp=igM6ChkKEzkxMTYyMTU3Njc1NDE4NTc0OTIQCBgDEhsKFW9yZy5raXdpeC5raXdpeG1vYmlsZRABGAMYAQ%3D%3D:S:ANO1ljKl_Lw&gsr=Cj2KAzoKGQoTOTExNjIxNTc2NzU0MTg1NzQ5MhAIGAMSGwoVb3JnLmtpd2l4Lmtpd2l4bW9iaWxlEAEYAxgB:S:ANO1ljLrUVU). [Wikimed - Offline Medical Wikipedia](https://play.google.com/store/apps/details?id=org.kiwix.kiwixcustomwikimed) and [Wikivoyage - Offline Travel Guide](https://play.google.com/store/apps/details?id=org.kiwix.kiwixcustomwikivoyage) being the most famous ones.
The general approach is to use `apt-get install` for the dependencies, Linux or Linux Subsystem recommended.
If your computer is running MacOS (OSX) then consider using `homebrew`.
This project contains data and scripts needed to create specific
custom Kiwix Android apps. _It does *not* create the app_, that's
done separately by running the relevant Gradle command to build one
or more custom apps.
```
## Prerequisites
Python 3 for the scripts in Python. On Debian based GNU/Linux you can
install it with:
```bash
apt-get install python3
```
[Imagemagick](https://imagemagick.org/) is needed by
`gen-std-icon.py`. On Debian based GNU/Linux you can
install it with:
```bash
apt-get install imagemagick
```
### OSX
Android studio is required to generate icon sets and can be downloaded
from [here](https://developer.android.com/studio/?gclid=Cj0KCQiAiNnuBRD3ARIsAM8KmlvCImKxWu_AGECa8YM5pM7Nr_algyHXSkfbPRTio3WEeKTaEfFiFeIaAs81EALw_wcB).
```
brew install python3
brew install imagemagick
On macOS, [Homebrew](https://brew.sh) allows to install the packages
`python3` and `imagemagick`.
## Badges
Custom apps use to have icon with two small badges to help user
understanding what the app is about:
* One reprsenting the language of the content
* One representing the stricked WiFi logo to emphasis its offline nature
The script `gen-std-icon.py` allows to add these two badges easily on
a master icon. You can use it that way:
```bash
python3 gen-std-icon.py [custom_app_directory]/icon_master.png [optional language code]
```
## Running the script
The script adds "badges" to a master icon, these badges are "offline" and "language"
The `custom_app_directory` needs to be one of the listed sub-folders
e.g. `phet`. If this is a new custom app, you will have to create it.
`python3 gen-std-icon.py [custom_app_directory]/icon_master.png [optional language code]`
The `optional language code` parameter for english would be `en`, if
you omit this parameter then no language badge is added, this is
desired in a few cases where the language is already clearly
indicated by the master icon e.g. `wikimedde`.
The `custom_app_directory` needs to be one of the listed sub-folders of this project e.g. `phet`
## Icon set
The `optional language code` parameter for english would be `en`,
if you omit this parameter then no language badge is added,
this is desired in a few cases where the language is already clearly indicated by the master icon eg `wikimedde`
The Android custom app needs an _Icon set_ to build properly. This
Icon set is a list of bitmap pictures which are derivatives of the
Icon master from the section above.
## Generating an icon set
1. Create a new empty project with Android Studio (add no activity>next>finish)
1. In the project view (top left) there should be a dropdown that says `Android`
select that and choose `Project`, this will make the project view display accurately to the file system
To create this Icon set, follow these steps:
1. Create a new empty project with Android Studio (add no activity >
next > finish)
1. In the project view (top left) there should be a dropdown that says
`Android` select that and choose `Project`, this will make the
project view display accurately to the file system
1. Delete `MyApplication/app/src/main/res`
1. Right click `MyApplication/app` in android studio, click `New>Image Asset`
to open Asset Studio (if this option is greyed out you will have to wait for indexing to finish, this shouldn't take longer than 2 minutes)
1. Right click `MyApplication/app` in android studio, click `New>Image
Asset` to open Asset Studio (if this option is greyed out you will
have to wait for indexing to finish, this shouldn't take longer than 2
minutes)
1. For `foreground layer` `Source Asset > Asset Type` choose `Image`
1. For `path` click the folder icon and browse to the output of `gen-std-icon.py`
1. For `path` click the folder icon and browse to the output of
`gen-std-icon.py`
1. For `background layer` `Source Asset > Asset Type` choose `Color`
1. Click on the color box
1. This should present the color chooser, the box in the top right with the label `#` should be auto selected.
Type `FFFFFF` to supply white as the color, this is typically the color used
1. [Optional] go back to foreground layer and size the icon as appropriate with the slider
1. Next>Finish will generate a res folder with all the icons needed in the location where you previously deleted the res folder.
1. Cut and paste the res folder to `kiwix-android-custom/whatever-directory-this-icon-set-is-for`
1. This should present the color chooser, the box in the top right
with the label `#` should be auto selected. Type `FFFFFF` to supply
white as the color, this is typically the color used
1. [Optional] go back to foreground layer and size the icon as
appropriate with the slider
1. Next > Finish will generate a res folder with all the icons needed in
the location where you previously deleted the res folder.
1. Cut and paste the res folder to
`kiwix-android-custom/whatever-directory-this-icon-set-is-for`
These instructions are for a first time setup, you can reuse this project
in the future for icon generation so many steps can be omitted.
These instructions are for a first time setup, you can reuse this
project in the future for icon generation so many steps can be
omitted.
## Building the custom Android app
Copy a custom app directory to `kiwix-android/custom/src`.
If using Android Studio this will add the build variant and you can install as you would any app.
## Version name
Alternatively run `./gradlew install[CustomAppNameWithFirstLetterCapitalised]Debug`
eg `./gradlew installPhetDebug` from the kiwix-android folder
The custom app will have a version name displayed on the Google Play
store. This version name has to be a date in the format YYYY-MM (for
example `2018-10`. This version name should be the date of the content
(neither the date of the Software nor the release date).
## Using a custom app locally
The custom app, as built and installed by the gradle script currently _does not
include the ZIM file_ but it does prompt you to download the file if it doesn't find an `.obb`.
So unless you need to test obb file reading you can stop here.
The app version name is determined in that order:
1. The date can be hardcoded in the json file at the key
`version_name`. Considering that this needs maintenance and that the
publisher can easily create a discrepency with the ZIM content date,
this should probably be avoided in most of the time.
1. If nothing is specified in the json, then it tries to extract it
from the ZIM file name. If the file - specified in `zim_url` - is
`wikipedia_en_all_maxi_2018-10.zim` then it will be `2018-10`.
1. Otherwise the current date will be put (should be avoided).
To test reading obb files you need the content to be on the device.
Here's an overview of the steps involved. You may need to tweak these for your app, environment and device, etc.
## Releasing
Download the ZIM file to your computer or on your device e.g. for PhET download
the ZIM file specified in https://github.com/kiwix/kiwix-android-custom/blob/master/phet/info.json by `"zim_url":`.
Get this onto the device in the folder `/sdcard` e.g. using the Android `adb push` command-line utility or more
simply by using Device File Exlporer in Android Studio. Copy this file to the location expected by the app.
This is often a deeply nested folder, and with a complex filename that's constructed based on parameters
used when creating the custom app. Here's an example of the command I used on a locally connected device
that is configured as a developer's device (details of how to do this are beyond the scope of these notes).
Simply tag the repo in git with the name of a custom app eg
`wikimed`. This triggers a Github action that will build an app using
kiwix-android master branch and the icon set/json defined in this
repository and then upload it to the Play Console in draft to alpha
with an expansion file attached.
This will only work with app updates. To create a new custom app an
app must be built manually and submit to the Google Play store
## Building Locally
First of all the Kiwix Android needs to be cloned locally:
```bash
git clone https://github.com/kiwix/kiwix-android.git
```
Copy then a custom app directory to `kiwix-android/custom/src`. If
using Android Studio this will add the build variant and you can
install as you would any app.
Alternatively - if you are more export - you can run `./gradlew
install[CustomAppNameWithFirstLetterCapitalised]Debug` eg `./gradlew
installPhetDebug` from the kiwix-android folder
## Testing locally
The custom app, as built and installed by the Gradle script currently
_does not include the ZIM file_ but it does prompt you to download
the file if it doesn't find an `.obb` (this is the extension for ZIM
files in custom app). So unless you need to test obb file reading
you can stop here.
To test reading an `.obb` file you need the file to be on the device.
Here's an overview of the steps involved. You may need to tweak these
for your app, environment and device, etc.
Download first the ZIM file to your computer e.g. for PhET download
the ZIM file specified in
https://github.com/kiwix/kiwix-android-custom/blob/master/phet/info.json
by the json key `zim_url`.
The Android obb dedicated directory is not always at the exact same
place on the Android device, usually it can be found at
`/sdcard/Android/obb/`. One time you will have found it, you will have
to create a directory for your custom app based on its Android id, for
example `org.kiwix.kiwixcustomphet` (`org.kiwix.kiwixcustom` + name of
the app directory).
You have then to get the ZIM file onto the device custom app obb
folder using the Android `adb push` command-line utility or more
simply by using Device File Exlporer in Android Studio. The obb
filename should be `main.4.` + app id + `.obb`. Here's an example:
```bash
adb push ~/Downloads/kiwix/phet_mul_2019-06.zim /sdcard/
adb shell
cd /sdcard/Android/obb/
mkdir org.kiwix.kiwixcustomphet
cd org.kiwix.kiwixcustomphet
cp /sdcard/phet_mul_2019-06.zim main.4.org.kiwix.kiwixcustomphet.obb
mv /sdcard/phet_mul_2019-06.zim main.4.org.kiwix.kiwixcustomphet.obb
```
## Releasing an App
Simply tag the repo in git with the name of a custom app eg `wikimed`.
This triggers a github action that will build an app using kiwix-android master branch
and the icon set/json defined in this repository and then upload it to the Play Console in draft to alpha with an expansion file attached.
This will only work with app updates. To create a new custom app an app must be built manually and submitted to the play store

3
wikimed/info.json
View File

@ -1,6 +1,5 @@
{
"app_name": "Medical Wikipedia",
"version_name": "2018-08",
"zim_url": "https://download.kiwix.org/zim/wikipedia_en_medicine_novid.zim",
"zim_url": "https://download.kiwix.org/zim/wikipedia/wikipedia_en_medicine_maxi_2019-10.zim",
"enforced_lang": "en"
}

3
wpbm/info.json
View File

@ -36,8 +36,7 @@
"defaultLanguage": "en-US"
}
},
"version_code": "5",
"embed_zim": false,
"zim_url": "https://download.kiwix.org/zim/wikipedia/wikipedia_bm_all_maxi_2019-10.zim",
"enforced_lang": "bm",
"version_name": "2015-06"
}