Android documentation "quick start example" doesn't work as written

[SomeoneElseOSM]

MapLibre Android Version

n/a

Android SDK Version

n/a

Device

n/a

What happened?

Find front page of documentation
https://maplibre.org/maplibre-native/android/examples/

Click link below "Learn how to include MapLibre Android in your project"
https://maplibre.org/maplibre-native/android/examples/getting-started/

That says "Add bintray Maven repositories to your project-level Gradle file (usually //build.gradle)." and there's some code. There's a "copy to clipboard" option which suggests that that code can literally just be copied in.

Steps to reproduce

Unfortunately, it can't. It contains "..." which presumably means that it needs to be merged with some existing code in some way, but what or how is not described.

The actual contents of the top-level build.gradle (and whether it exists at all) will depend on what sort of project was created in Android Studio as the "New Project" and what was selected on subsequent screens for e.g. language and build system.

Renderer

No response

Relevant log output

n/a

Additional context

No response

[louwers]

Thanks for the feedback.

I agree we should make the Getting Started guide as approachable as possible.

[SomeoneElseOSM]

Just to add a bit more information here, perhaps it should be mentioned that the text "Add bintray Maven repositories to your project-level Gradle file", as well as not mentioning what sort of project to create so that you end up with a "build.gradle" file, doesn't actually say where to add the text.

Addd it at the top and you'll get one error:

Build file '/usr2/home/ajtown/AndroidStudioProjects/MyApplication5/app/build.gradle' line: 7

Could not compile build file '/usr2/home/ajtown/AndroidStudioProjects/MyApplication5/app/build.gradle'.
> startup failed:
  build file '/usr2/home/ajtown/AndroidStudioProjects/MyApplication5/app/build.gradle': 7: only buildscript {    }, pluginManagement {} and other plugins {} script blocks are allowed before plugins {} blocks, no other statements are allowed

add it after the first block and you'll get

Caused by: org.gradle.api.InvalidUserCodeException: Build was configured to prefer settings repositories over project repositories but repository 'MavenRepo' was added by build file 'app/build.gradle'

and move to the end and you'll get a different error again

Build file '/usr2/home/ajtown/AndroidStudioProjects/MyApplication5/app/build.gradle' line: 44

A problem occurred evaluating project ':app'.
> Build was configured to prefer settings repositories over project repositories but repository 'MavenRepo' was added by build file 'app/build.gradle'

* Try:
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.

* Exception is:
org.gradle.api.GradleScriptException: A problem occurred evaluating project ':app'.
	at org.gradle.groovy.scripts.internal.DefaultScriptRunnerFactory$ScriptRunnerImpl.run(DefaultScriptRunnerFactory.java:93)
	(snip)

Looking for errors somewhat similar to this finds https://stackoverflow.com/questions/69163511/build-was-configured-to-prefer-settings-repositories-over-project-repositories-b#69197871 which actually suggests that build.gradle may actually not be the right place for this setting at all. Interestingly that SO question dates from some time before the documentation .md https://github.com/maplibre/maplibre-native/blob/main/platform/android/docs/getting-started.md was created.

What is really needed here is a set of steps that someone with a new copy of Android Studio can follow - literally what buttons to press in what order - to get a "basic" application that shows a demo map. Customisation and adding features can follow that. Until that is done the people who can actually use anything here is very limited, I'd imagine mostly to people who already have something working in the Mapbox world.

[SomeoneElseOSM]

From further trial and error, the page should probably say at the top to select "Empty Views Activity" and then to select "Kotlin" as a language. The maven setting appears already to be in settings.gradle; Groovy needs to be select so that "build.gradle" exists to be edited.

Further down "import org.maplibre.android.Maplibre" needs changing to "import org.maplibre.android.MapLibre".

Further down I suspect that "import org.maplibre.android.testapp.R" can be removed (and if not, I'm guessing, renamed to match the test app name).

[louwers]

If you're inclined to make a PR, you can check out the instructions here to build the documentation. https://maplibre.org/maplibre-native/docs/book/android/android-documentation.html#building

Otherwise I'll incorporate your suggestions. Thanks again for the feedback!