Skip to content

Commit c7e6b0c

Browse files
louwerslouwers
authored
Consolidate developer documentation in mdBook docs (#3115)
1 parent 660f78c commit c7e6b0c

14 files changed

+320
-131
lines changed

‎docs/mdbook/README.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,11 @@
22

33
## Build Locally
44

5-
Get the `mdbook` utility, see https://rust-lang.github.io/mdBook/guide/installation.html
5+
Get the `mdbook` utility as well as [`mdbook-alerts`](https://github.com/lambdalisue/rs-mdbook-alerts), see https://rust-lang.github.io/mdBook/guide/installation.html
6+
7+
```
8+
cargo install mdbook mdbook-alerts
9+
```
610

711
Run
812

‎docs/mdbook/book.toml

+3-1
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,9 @@ authors = ["MapLibre Contributors"]
33
language = "en"
44
multilingual = false
55
src = "src"
6-
title = "MapLibre Native Documentation"
6+
title = "MapLibre Native Developer Documentation"
77

88
[output.html]
99
additional-css = ["diff.css"]
10+
11+
[preprocessor.alerts]

‎docs/mdbook/src/SUMMARY.md

+17-7
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,23 @@
22

33
[Introduction](./introduction.md)
44

5+
- [Platforms](./platforms.md)
6+
7+
- [Android](./android/README.md)
8+
- [Tests](./android/android-tests.md)
9+
- [Documentation](./android/android-documentation.md)
10+
11+
- [iOS](./ios/README.md)
12+
- [Tests](ios/ios-tests.md)
13+
- [Documentation](ios/ios-documentation.md)
14+
515
- [Design](./design/README.md)
6-
- [Ten Thousand Foot View](design/ten-thousand-foot-view.md)
7-
- [Coordinate System](design/coordinate-system.md)
8-
- [Expressions](design/expressions.md)
9-
- [Architectural Problems and Recommendations](design/archictural-problems-and-recommendations.md)
10-
- [Android Map Rendering Data Flow](design/android-map-rendering-data-flow.md)
11-
- [Geometry Tile Worker](design/geometry-tile-worker.md)
16+
- [Ten Thousand Foot View](design/ten-thousand-foot-view.md)
17+
- [Coordinate System](design/coordinate-system.md)
18+
- [Expressions](design/expressions.md)
19+
- [Architectural Problems and Recommendations](design/archictural-problems-and-recommendations.md)
20+
- [Android Map Rendering Data Flow](design/android-map-rendering-data-flow.md)
21+
- [Geometry Tile Worker](design/geometry-tile-worker.md)
1222

1323
- [Profiling applications that use MapLibre Native](./profiling/README.md)
14-
- [Tracy profiling](./profiling/tracy-profiling.md)
24+
- [Tracy profiling](./profiling/tracy-profiling.md)

‎platform/android/DEVELOPING.md ‎docs/mdbook/src/android/README.md

+2-37
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Developing - MapLibre Native for Android
1+
# MapLibre Android Developer Guide
22

33
These instructions are for developers interested in making code-level contributions to MapLibre Native for Android.
44

@@ -33,34 +33,6 @@ Run the configuration for the `MapLibreAndroidTestApp` module and select a devic
3333
<img src="https://github.com/maplibre/maplibre-native/assets/649392/5494925e-8cbb-4d5d-8033-8a2f141ede3c" alt="Android TestApp menu" width="15%"> <img src="https://github.com/maplibre/maplibre-native/assets/649392/f169db51-615d-4fca-b297-ac6197bec674" alt="Android TestApp showing Demotiles" width="15%">
3434
</p>
3535

36-
## Render Tests
37-
38-
To run the render tests for Android, run the configuration for the `androidRenderTest.app` module.
39-
40-
More information on working on the render tests can be found [in the wiki](https://github.com/maplibre/maplibre-native/wiki/Working-on-Android-Render-Tests).
41-
42-
## Instrumentation Tests
43-
44-
To run the instrumentation tests, choose the "Instrumentation Tests" run configuration.
45-
46-
Your device needs remain unlocked for the duration of the tests.
47-
48-
## C++ Unit Tests
49-
50-
There is a separate Gradle project that contains a test app which runs the C++ Unit Tests. It does not depend on the Android platform implementations.
51-
52-
You can find the project in `test/android.` You can open this project in Android Studio and run the C++ Tests on an Android device or Simulator.
53-
54-
To run a particular set of tests you can modify the `--gtest_filter` flag in `platform/android/src/test/test_runner.cpp`. See the [GoogleTest documentation](https://google.github.io/googletest/advanced.html#running-a-subset-of-the-tests) for details how to use this flag.
55-
56-
### AWS Device Farm
57-
58-
The instrumentation tests and C++ unit tests are running on AWS Device Farm. To see the results and the logs, go to:
59-
60-
https://us-west-2.console.aws.amazon.com/devicefarm/home?region=us-east-1#/mobile/projects/20687d72-0e46-403e-8f03-0941850665bc/runs
61-
62-
You can log in with the `maplibre` alias, with `maplibre` as username and `maplibre` as password (this is a read-only account).
63-
6436
## Kotlin
6537

6638
All new code should be written in [Kotlin](https://kotlinlang.org/).
@@ -91,11 +63,4 @@ To run the benchmarks (for Android) include the following line on a PR comment:
9163

9264
## Profiling
9365

94-
[maplibre-native/docs/mdbook](https://maplibre.org/maplibre-native/docs/book/) describes how Tracy can be used for profiling.
95-
96-
97-
## Documentation
98-
99-
We use Dokka for the API documentation.
100-
101-
The documentation site with examples uses MkDocs along with Material for MkDocs. For more information on how to work on the examples, see [`docs/README.md`](./docs/REAME.md`).
66+
See [Tracy Profiling](/profiling/tracy-profiling.md) to understand how Tracy can be used for profiling.

‎docs/mdbook/src/android/android-documentation.md

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Documentation for MapLibre Android
2+
3+
## API Documentation
4+
5+
We use Dokka for the MapLibre Android API documentation. The live documentation site can be found [here](https://maplibre.org/maplibre-native/android/api/).
6+
7+
## Examples Documentation
8+
9+
The documentation site with examples uses MkDocs along with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). You can check out the site [here](https://maplibre.org/maplibre-native/android/examples/).
10+
11+
### Building
12+
13+
To build the Examples Documentation you need to have Docker installed.
14+
15+
From `platform/android`, run:
16+
17+
```
18+
make mkdocs
19+
```
20+
21+
Next, visit [`http://localhost:8000/maplibre-native/android/examples/`](http://localhost:8000/maplibre-native/android/examples/).
22+
23+
### Snippets
24+
25+
We use [a Markdown extension for snippets](https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippet-sections). This way code can be referenced instead of copy pasted into the documentation. This avoids code examples from becoming out of date or failing to compile. The syntax is as follows:
26+
27+
````kotlin
28+
// --8<-- [start:fun]
29+
fun double(x: Int): Int {
30+
return 2 * x
31+
}
32+
// --8<-- [end:fun]
33+
````
34+
35+
Next, you'll be able to reference that piece of code in Markdown like so:
36+
37+
```
38+
--8<-- "example.kt:fun"
39+
```
40+
41+
Where `example.kt` is the path to the file.
42+
43+
### Static Assets
44+
45+
Static assets are ideally uploaded to the [MapLibre Native S3 Bucket](https://maplibre-native.s3.eu-central-1.amazonaws.com/index.html#android-documentation-resources/).
46+
47+
Please open an issue with the ARN of your AWS account to get upload privileges.
48+
49+
You can use the macro `{{ s3_url("filename.example") }}` which will use a CDN instead of linking to the S3 bucket directly.

‎docs/mdbook/src/android/android-tests.md

+91
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# MapLibre Android Tests
2+
3+
## Render Tests
4+
5+
To run the render tests for Android, run the configuration for the `androidRenderTest.app` module.
6+
7+
### Filtering Render Tests
8+
9+
You can filter the tests to run by passing a flag to the file `platform/android/src/test/render_test_runner.cpp`:
10+
11+
```cpp
12+
std::vector<std::string> arguments = {..., "-f", "background-color/literal"};
13+
```
14+
15+
### Viewing the Results
16+
17+
Once the application quits, use the Device Explorer to navigate to `/data/data/org.maplibre.render_test_runner/files`.
18+
19+
<img width="980" alt="image" src="https://github.com/maplibre/maplibre-native/assets/649392/0dc42d4a-6221-46b6-8352-1eb24d466e91">
20+
21+
Double click `android-render-test-runner-style.html`. Right click on the opened tab and select _Open In > Browser_. You should see that a single render test passed.
22+
23+
<img width="801" alt="image" src="https://github.com/maplibre/maplibre-native/assets/649392/33e88999-7787-492f-afd9-f5a3e3fd61f7">
24+
25+
Alternatively to download (and open) the results from the command line, use:
26+
27+
```
28+
adb shell "run-as org.maplibre.render_test_runner cat files/metrics/android-render-test-runner-style.html" > android-render-test-runner-style.html
29+
open android-render-test-runner-style.html
30+
```
31+
32+
### Updating the Render Tests
33+
34+
Now let's edit `metrics/integration/render-tests/background-color/literal/style.json`, change this line:
35+
36+
```
37+
"background-color": "red"
38+
```
39+
40+
to
41+
42+
```
43+
"background-color": "yellow"
44+
```
45+
46+
We need to make sure that the new `data.zip` with the data for the render tests is installed on the device. You can use the following commands:
47+
48+
```
49+
tar chf render-test/android/app/src/main/assets/data.zip --format=zip --files-from=render-test/android/app/src/main/assets/to_zip.txt
50+
adb push render-test/android/app/src/main/assets/data.zip /data/local/tmp/data.zip
51+
adb shell chmod 777 /data/local/tmp/data.zip
52+
adb shell "run-as org.maplibre.render_test_runner unzip -o /data/local/tmp/data.zip -d files"
53+
```
54+
55+
Rerun the render test app and reload the Device Explorer. When you re-open the HTML file with the results you should now see a failing test:
56+
57+
<img width="685" alt="image" src="https://github.com/maplibre/maplibre-native/assets/649392/303ad75a-cf74-4b8c-927c-c9bd59a79de4">
58+
59+
Now download the `actual.png` in `metrics/integration/render-tests/background-color/literal` with the Device Explorer. Replace the corresponding `expected.png` on your local file system. Upload the new render test data again and run the test app once more.
60+
61+
<img width="800" alt="image" src="https://github.com/maplibre/maplibre-native/assets/649392/04734c6a-9cf1-489a-b9bb-8d857581261c">
62+
63+
Of we don't want to commit this change. But know you can add and debug (Android) render tests.
64+
65+
## Instrumentation Tests
66+
67+
To run the instrumentation tests, choose the "Instrumentation Tests" run configuration.
68+
69+
Your device needs remain unlocked for the duration of the tests.
70+
71+
## C++ Unit Tests
72+
73+
There is a separate Gradle project that contains a test app which runs the C++ Unit Tests. It does not depend on the Android platform implementations.
74+
75+
You can find the project in `test/android.` You can open this project in Android Studio and run the C++ Tests on an Android device or Simulator.
76+
77+
To run a particular set of tests you can modify the `--gtest_filter` flag in `platform/android/src/test/test_runner.cpp`. See the [GoogleTest documentation](https://google.github.io/googletest/advanced.html#running-a-subset-of-the-tests) for details how to use this flag.
78+
79+
### AWS Device Farm
80+
81+
The instrumentation tests and C++ unit tests are running on AWS Device Farm. To see the results and the logs, go to:
82+
83+
[https://us-west-2.console.aws.amazon.com/devicefarm/home?region=us-east-1#/mobile/projects/20687d72-0e46-403e-8f03-0941850665bc/runs](https://us-west-2.console.aws.amazon.com/devicefarm/home?region=us-east-1#/mobile/projects/20687d72-0e46-403e-8f03-0941850665bc/runs).
84+
85+
Use the following login details (this is a read-only account):
86+
87+
| | |
88+
|------------|------------|
89+
| Alias | `maplibre` |
90+
| Username | `maplibre` |
91+
| Password | `maplibre` |

‎docs/mdbook/src/design/README.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
> [!NOTE]
2+
> These notes are partially outdated since the [renderer modularization](https://github.com/maplibre/maplibre-native/blob/main/design-proposals/2022-10-27-rendering-modularization.md).
3+
14
# Design
25

3-
This section is dedicated to documenting current state of MapLibre Native. [Architectural Problems and Recommendations](./archictural-problems-and-recommendations.md) section notes recommendations for future improvements from an architectural perspective.
6+
This section is dedicated to documenting current state of MapLibre Native as of end 2022. [Architectural Problems and Recommendations](./archictural-problems-and-recommendations.md) section notes recommendations for future improvements from an architectural perspective.

‎docs/mdbook/src/introduction.md

+2
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,5 @@
33
*[MapLibre Native](https://github.com/maplibre/maplibre-native)* is a community led fork of *Mapbox GL Native*. It's a C++ library that powers
44
vector maps in native applications on multiple platforms by taking stylesheets that conform to the *[MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/)*, a fork of the
55
Mapbox Style Spec. Since it is derived from Mapbox's original work it also uses *Mapbox Vector Tile Specification* as its choice of vector tile format.
6+
7+
This documentation is intended for developers of MapLibre Native. If you are interested in *using* MapLibre Native, check out the [main `README.md`](https://github.com/maplibre/maplibre-native?tab=readme-ov-file#maplibre-native) on GitHub.

‎platform/ios/CONTRIBUTING.md ‎docs/mdbook/src/ios/README.md

+12-80
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,4 @@
1-
# Contributing
2-
3-
## Downloading Source
4-
5-
Download the source and install all submodules if you have not already, by running the following from the root of the repository.
6-
7-
```
8-
git clone --recurse-submodules git@github.com:maplibre/maplibre-native.git
9-
cd maplibre-native
10-
```
1+
# MapLibre iOS Developer Guide
112

123
## Bazel
134

@@ -56,91 +47,32 @@ Try to run the example App in the simulator and on a device to confirm your setu
5647
> [!IMPORTANT]
5748
> The Bazel configuration files are the source of truth of the build configuration. All changes to the build settings need to be done through Bazel, not in Xcode.
5849
59-
### Troubleshooting Provisioning Profiles
50+
### Troubleshooting
51+
52+
#### Provisioning Profiles
6053

6154
If you get a Python `KeyError` when processing provisioning profiles, you probably have some _really_ old or corrupted profiles.
6255

6356
Have a look through `~/Library/MobileDevice/Provisioning\ Profiles` and remove any expired profiles. Removing all profiles here can also resolve some issues.
6457

65-
## Using Bazel from the Command Line
58+
#### Cleaning Bazel environments
6659

67-
It is also possible to build and run the test application in a simulator from the command line without opening Xcode.
60+
You should almost never have to do this, but sometimes problems can be solved with:
6861

6962
```
70-
bazel run //platform/ios:App --//:renderer=metal
63+
bazel clean --expunge
7164
```
7265

73-
You can also build targets from the command line. For example, if you want to build your own XCFramework, see the 'Build XCFramework' step in the [iOS CI workflow](../../.github/workflows/ios-ci.yml).
74-
75-
## Render Tests
76-
77-
To run the render tests, run the `RenderTest` target from iOS.
66+
## Using Bazel from the Command Line
7867

79-
When running in a simulator, use
68+
It is also possible to build and run the test application in a simulator from the command line without opening Xcode.
8069

8170
```
82-
# check for 'DataContainer' of the app with `*.maplibre.RenderTestApp` id
83-
xcrun simctl listapps booted
71+
bazel run //platform/ios:App --//:renderer=metal
8472
```
8573

86-
to get the data directory of the render test app. This allows you to inspect test results. When adding new tests, the generated expectations and `actual.png` file can be copied into the source directory from here.
87-
88-
## C++ Unit Tests
89-
90-
Run the tests from the `CppUnitTests` target in Xcode to run the C++ Unit Tests on iOS.
74+
You can also build targets from the command line. For example, if you want to build your own XCFramework, see the 'Build XCFramework' step in the [iOS CI workflow](../../.github/workflows/ios-ci.yml).
9175

9276
## Swift App
9377

94-
There is also an example app built with Swift instead of Objective-C. The target is called `MapLibreApp` and the source code lives in `platform/ios/app-swift`.
95-
96-
## Documentation
97-
98-
We use [DocC](https://www.swift.org/documentation/docc) for documentation. You need to have [aws-cli](https://github.com/aws/aws-cli) installed to download the resources from S3 (see below). Run the following command:
99-
100-
```
101-
aws s3 sync --no-sign-request "s3://maplibre-native/ios-documentation-resources" "platform/ios/MapLibre.docc/Resources"
102-
```
103-
104-
Then, to build the documentation locally, run the following command:
105-
106-
```
107-
platform/ios/scripts/docc.sh preview
108-
```
109-
110-
### Resources
111-
112-
Resources like images should not be checked in but should be uploaded to the [S3 Bucket](https://s3.eu-central-1.amazonaws.com/maplibre-native/index.html#ios-documentation-resources/). You can share a `.zip` with all files that should be added in the PR.
113-
114-
If you want to get direct access you need an AWS account to get permissions to upload files. Create an account and authenticate with aws-cli. Share the account ARN that you can get with
115-
116-
```
117-
aws sts get-caller-identity
118-
```
119-
120-
### Examples
121-
122-
The code samples in the documentation should ideally be compiled on CI so they do not go out of date.
123-
124-
Fence your example code with
125-
126-
```swift
127-
// #-example-code(LineTapMap)
128-
...
129-
// #-end-example-code
130-
```
131-
132-
Prefix your documentation code block with
133-
134-
````md
135-
<!-- include-example(LineTapMap) -->
136-
137-
```swift
138-
...
139-
```
140-
````
141-
142-
Then the code block will be updated when you run:
143-
144-
```sh
145-
node scripts/update-ios-examples.mjs
146-
```
78+
There is also an example app built with Swift instead of Objective-C. The target is called `MapLibreApp` and the source code lives in `platform/ios/app-swift`.

0 commit comments

Comments
 (0)