From 16f5cd014fd86779d223f9339ecd37257b0bd3df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s=20Miguel=20Rubio?= Date: Mon, 15 Jul 2024 13:42:39 +0200 Subject: [PATCH] doc:[ANDROAPP-6256] create a getting started file (#258) * doc:[ANDROAPP-6256] create a getting started file * doc: Add Testing folder in docs * doc: add documentation section in README file --------- Co-authored-by: Victor Garcia --- README.md | 25 +++++++++++ docs/getting-started.md | 67 ++++++++++++++++++++++++++++++ docs/testing/_category_.yml | 2 + docs/testing/recomposition.md | 21 ++++++++++ docs/testing/screenshot-testing.md | 50 ++++++++++++++++++++++ 5 files changed, 165 insertions(+) create mode 100644 docs/getting-started.md create mode 100644 docs/testing/_category_.yml create mode 100644 docs/testing/recomposition.md create mode 100644 docs/testing/screenshot-testing.md diff --git a/README.md b/README.md index a0b906bea..8d351e5a4 100644 --- a/README.md +++ b/README.md @@ -109,3 +109,28 @@ Saves snapshots as golden values to a predefined source-controlled location (def Runs tests and verifies against previously-recorded golden values. Failures generate diffs at `/build/paparazzi/failures`. + +# Documentation + +The Mobile UI documentation is integrated in the [developer portal](https://developers.dhis2.org/). It +uses [Docusaurus](https://docusaurus.io), a modern tool to build documentation pages. + +The documentation is written in Markdown. The sidebar is automatically generated based on the metadata +of the different files. It follows the rules explained in the [autogenerated sidebar docs](https://docusaurus.io/docs/next/sidebar/autogenerated#autogenerated-sidebar-metadata). +In short, every file must have a `sidebar_position` label at the beginning of the document, which +defines the position of the document relative to its folder. Then, each folder has a `_category_.yml` +file, which has a `position` property defining the position of that folder relative to its parent folder. + +It is possible to nest as many folders as desired following that pattern. + +## Testing + +It is possible to build the Developers portal documentation to test your changes. + +Steps to test: +1. Do the changes in the Mobile UI docs and push them to a branch in github. +2. Download the [Deverlopers portal repository](https://github.com/dhis2/developer-portal). +3. Change the branch in the Mobile UI block in the file `docs-migrate.js` to point to your branch. +4. Follow the instructions in [CONTRIBUTING](https://github.com/dhis2/developer-portal/blob/main/CONTRIBUTING.md) +to build the docs. + diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 000000000..803c7703c --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,67 @@ +--- +id: getting-started +title: Getting started +sidebar_position: 1 +--- + +# DHIS2 Mobile UI + +> **@dhis2/dhis2-mobile-ui** is +> a [Compose Multiplatform](https://www.jetbrains.com/lp/compose-multiplatform/) DHIS2 design system +> library for [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) applications. + +**DHIS2 Mobile UI library** is based in +the [DHIS2 Mobile Design System Figma library](https://www.figma.com/file/eRk6bt0B8BJlTO9PZXirHN/DHIS2-Mobile-Design-System). + +This library currently supports **desktop** and **Android** targets, in the next versions it will +support **iOS**. + +## 1. Getting started + +### DHIS2 UI Library Principles + +The UI library more than just a collection of components, there also are principles, such as predefined colors, layout, typography, icons and patterns. You can find all of these in the [DHIS2 UI documentation](https://ui.dhis2.nu/). + +### Live demos documentation + +//TODO link to github releases artifact maybe? + +### Installation + +In the module **build.gradle.kts**: + +```kotlin +dependencies { + implementation("org.hisp.dhis.mobile:designsystem:0.2") +} +``` + +## 2. Usage + +```kotlin +setContent { + DHIS2Theme { + // A surface container using the 'background' color from the theme + Surface( + modifier = Modifier.fillMaxSize(), + color = SurfaceColor.Container + ) { + Components() + } + } +} +``` + +### Add a Button +```kotlin +Button( + text = provideStringResource("show_more"), + icon = { + Icon( + painter = provideDHIS2Icon(resourceName = "dhis2_blood_a_n_positive"), + contentDescription = "" + ) + }, + style = ButtonStyle.KEYBOARDKEY +) {} +``` \ No newline at end of file diff --git a/docs/testing/_category_.yml b/docs/testing/_category_.yml new file mode 100644 index 000000000..4137e9b42 --- /dev/null +++ b/docs/testing/_category_.yml @@ -0,0 +1,2 @@ +position: 2 +label: 'Testing' diff --git a/docs/testing/recomposition.md b/docs/testing/recomposition.md new file mode 100644 index 000000000..ca9a5953d --- /dev/null +++ b/docs/testing/recomposition.md @@ -0,0 +1,21 @@ +--- +id: recomposition +title: Recomposition +sidebar_position: 1 +--- + +# Recomposition + +The Compose Compiler plugin can generate reports / metrics around certain compose-specific concepts +that can be useful to understand what is happening with some of your compose code at a fine-grained +level. +You can read more about +it [here](https://github.com/androidx/androidx/blob/androidx-main/compose/compiler/design/compiler-metrics.md). + +To generate the reports / metrics, run the following Gradle command + +```shell +./gradlew assembleDebug -PenableComposeCompilerReports=true +``` + +This would generate the output at `/build/compose_metrics`. \ No newline at end of file diff --git a/docs/testing/screenshot-testing.md b/docs/testing/screenshot-testing.md new file mode 100644 index 000000000..b914c886a --- /dev/null +++ b/docs/testing/screenshot-testing.md @@ -0,0 +1,50 @@ +--- +id: screenshot-testing +title: Screenshot testing +sidebar_position: 2 +--- + +# Screenshot Testing + +We are using [Paparazzi](https://cashapp.github.io/paparazzi/) for screenshot testing. + +## Screenshot testing + +```kotlin +class InputChipSnapshotTest { + + @get:Rule + val paparazzi = paparazzi() + + @Test + fun launchChip() { + paparazzi.snapshot { + ColumnComponentContainer { + InputChip(label = "Label", selected = false, badge = "3") + InputChip(label = "Label", selected = true, badge = "3") + } + } + } +} +``` + +## Running tests + +`./gradlew designsystem:testDebugUnitTest` + +Runs tests and generates an HTML report at `/build/reports/paparazzi/` showing all test runs +and snapshots. + +## Saving golden images to repo + +`./gradlew designsystem:recordPaparazziDebug` + +Saves snapshots as golden values to a predefined source-controlled location (defaults to +`/src/test/snapshots`). + +## Verifying + +`./gradlew designsystem:verifyPaparazziDebug` + +Runs tests and verifies against previously-recorded golden values. Failures generate diffs at +`/build/paparazzi/failures`. \ No newline at end of file