Merge pull request #216 from takahirom/takahirom/introduce-writerside…

…-documentation/2023-12-03

Add Roborazzi documentation using Writerside

.github/workflows/deploy-docs.yml

@@ -0,0 +1,103 @@
+name: Build documentation
+
+on:
+# If specified, the workflow will be triggered automatically once you push to the `main` branch.
+# Replace `main` with your branch’s name
+    push:
+        branches: ["main"]
+# Specify to run a workflow manually from the Actions tab on GitHub
+    workflow_dispatch:
+
+# Gives the workflow permissions to clone the repo and create a page deployment
+permissions:
+    id-token: write
+    pages: write
+
+env:
+    # Name of module and id separated by a slash
+    INSTANCE: Writerside/roborazzi-docs
+    ARTIFACT: web-roborazzi-docs-all.zip
+    # Writerside docker image version
+    DOCKER_VERSION: 232.10275
+# Add the variable below to upload Algolia indexes
+#    ALGOLIA_ARTIFACT: algolia-indexes-roborazzi-docs.zip
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+
+        steps:
+        - name: Checkout repository
+          uses: actions/checkout@v3
+
+        - name: Build Writerside docs using Docker
+          uses: JetBrains/writerside-github-action@v4
+          with:
+            instance: ${{ env.INSTANCE }}
+            artifact: ${{ env.ARTIFACT }}
+            docker-version: ${{ env.DOCKER_VERSION }}
+
+        - name: Upload documentation
+          uses: actions/upload-artifact@v3
+          with:
+            name: docs
+            path: |
+                artifacts/${{ env.ARTIFACT }}
+                artifacts/report.json
+            retention-days: 7
+
+# Add the step below to upload Algolia indexes
+#        - name: Upload algolia-indexes
+#          uses: actions/upload-artifact@v3
+#          with:
+#            name: algolia-indexes
+#            path: artifacts/${{ env.ALGOLIA_ARTIFACT }}
+#            retention-days: 7
+
+# Add the job below and artifacts/report.json on Upload documentation step above if you want to fail the build when documentation contains errors
+    test:
+    # Requires build job results
+        needs: build
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Download artifacts
+              uses: actions/download-artifact@v1
+              with:
+                name: docs
+                path: artifacts
+
+            - name: Test documentation
+              uses: JetBrains/writerside-checker-action@v1
+              with:
+                instance: ${{ env.INSTANCE }}
+
+    deploy:
+        environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+        # Requires the build job results
+        needs: test
+        runs-on: ubuntu-latest
+        steps:
+            - name: Download artifact
+              uses: actions/download-artifact@v3
+              with:
+                name: docs
+
+            - name: Unzip artifact
+              uses: montudor/action-zip@v1
+              with:
+                args: unzip -qq ${{ env.ARTIFACT }} -d dir
+
+            - name: Setup Pages
+              uses: actions/configure-pages@v2
+
+            - name: Upload artifact
+              uses: actions/upload-pages-artifact@v1
+              with:
+                path: dir
+
+            - name: Deploy to GitHub Pages
+              id: deployment
+              uses: actions/deploy-pages@v1

README.md

@@ -1,3 +1,6 @@
+<!-- Generated by ./gradlew generateReadme. Do not edit this file. -->
+<div name="topic_top">
+<!-- Generated by docs/topics/top.md. Do not edit this file. -->
 # Roborazzi
 
 **Make JVM Android Integration Test Visible**
@@ -39,7 +42,10 @@ efficient and reliable testing process by capturing screenshots with Robolectric
 
 In the DroidKaigi 2023 app, Roborazzi was introduced from the early stages of development as part of the architectural design. This integration allowed the team to verify changes throughout the development process. The specific architectural decisions and how they were implemented can be found [README](https://github.com/DroidKaigi/conference-app-2023#screenshot-testing-with-robolectric-native-graphics-rng-and-roborazzi).
 
-## Try it out
+</div>
+<div name="topic_try_it_out">
+<!-- Generated by docs/topics/try_it_out.md. Do not edit this file. -->
+# Try it out
 
 Available on Maven Central.
 
@@ -210,7 +216,7 @@ The comparison image, saved as `[original]_compare.png`, is shown below:
 
 You can check the test report in `build/reports/roborazzi/index.html`
 
-<img width="400" alt="image" src="https://github.com/takahirom/roborazzi/assets/1386930/7834a436-1927-438d-8656-61f583ae3f48">
+<img width="400" alt="image" src="https://github.com/takahirom/roborazzi/assets/1386930/7834a436-1927-438d-8656-61f583ae3f48" />
 
 
 This
@@ -226,7 +232,10 @@ compose-samples [here](https://github.com/takahirom/compose-samples/pull/1/files
 | Jetpack Compose | `testImplementation("io.github.takahirom.roborazzi:roborazzi-compose:[version]")`    |
 | JUnit rules     | `testImplementation("io.github.takahirom.roborazzi:roborazzi-junit-rule:[version]")` |
 
-## How to use
+</div>
+<div name="topic_how_to_use">
+<!-- Generated by docs/topics/how_to_use.md. Do not edit this file. -->
+# How to use
 
 ### Take a screenshot manually
 
@@ -966,7 +975,7 @@ You can configure the following options in your `gradle.properties` file:
 
 ### roborazzi.test
 
-This option enables you to configure the behavior of Roborazzi. By default, all settings are set to false. 
+This option enables you to configure the behavior of Roborazzi. By default, all settings are set to false.
 For additional configuration options, please refer to the 'Apply Roborazzi Gradle Plugin' section.
 
 ```properties
@@ -1005,6 +1014,9 @@ This option enables you to define the naming strategy for the recorded image. Th
 roborazzi.record.namingStrategy=testClassAndMethod
 ```
 
+</div>
+<div name="topic_faq">
+<!-- Generated by docs/topics/faq.md. Do not edit this file. -->
 # FAQ
 
 ### Q: How can I run only screenshot tests using Roborazzi?
@@ -1102,6 +1114,8 @@ roborazzi {
     outputDir = "src/your/screenshot/folder"
 }
 ```
+</div>
+</div>
 
 ### LICENSE
 

build.gradle

@@ -1,3 +1,6 @@
+import java.util.regex.Matcher
+import java.util.regex.Pattern
+
 plugins {
   id 'com.android.application' version libs.versions.agp apply false
   id 'com.android.library' version libs.versions.agp apply false
@@ -48,3 +51,48 @@ allprojects {
     }
   }
 }
+
+class Topic {
+    String name
+    String content
+
+    @Override
+    String toString() {
+        return "Topic(name: $name, content: ...)"
+    }
+}
+
+def topicsPath = "docs/topics"
+def topicsDir = rootProject.file(topicsPath)
+def readme = rootProject.file("README.md")
+// Generate README.md from docs/topics/topic_name.md files by coping
+// Insert topics into <topics=name="...">...</topics> by name in README.md
+tasks.register("generateReadme") {
+    doLast {
+        def readmeContent = readme.text
+        def topicFiles = []
+        topicsDir.eachFileRecurse { file ->
+            if (file.name.endsWith(".md")) {
+                topicFiles.add(file)
+            }
+        }
+        def topics = topicFiles.collect { file ->
+            def name = file.name.substring(0, file.name.length() - ".md".length())
+            def content = Matcher.quoteReplacement(file.text)
+            new Topic(name: name, content: content)
+        }
+        def newReadmeContent = readmeContent
+        println(topics)
+        topics.forEach { topic ->
+            def pattern = Pattern.compile("<div name=\"topic_${topic.name}\">.*?</div>", Pattern.DOTALL)
+            def result = pattern.matcher(newReadmeContent).find()
+            println("topic: $topic pattern: $pattern result: $result")
+
+            def generatedComment = "<!-- Generated by $topicsPath/${topic.name}.md. Do not edit this file. -->"
+            def newTopicContent = "<div name=\"topic_${topic.name}\">\n$generatedComment\n${topic.content}\n<\\/div>"
+            newReadmeContent = pattern.matcher(newReadmeContent)
+                    .replaceAll(newTopicContent)
+        }
+        readme.write(newReadmeContent)
+    }
+}

docs/c.list

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE categories
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/categories.dtd">
+<categories>
+    <category id="wrs" name="Writerside documentation" order="1"/>
+</categories>

docs/cfg/buildprofiles.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<buildprofiles xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+    <variables>
+        <enable-browser-edits>true</enable-browser-edits>
+        <header-logo>https://raw.githubusercontent.com/takahirom/roborazzi/main/.idea/icon.svg</header-logo>
+        <primary-color>blueberry</primary-color>
+        <browser-edits-url>https://github.com/takahirom/roborazzi/edit/main/docs/</browser-edits-url>
+    </variables>
+</buildprofiles>

docs/roborazzi-docs.tree

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE instance-profile
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
+
+<instance-profile id="roborazzi-docs"
+                 name="roborazzi-docs"
+                 start-page="top.md">
+
+    <toc-element topic="top.md"/>
+    <toc-element topic="try_it_out.md"/>
+    <toc-element topic="how_to_use.md"/>
+    <toc-element topic="faq.md"/>
+</instance-profile>

docs/topics/faq.md

@@ -0,0 +1,97 @@
+# FAQ
+
+### Q: How can I run only screenshot tests using Roborazzi?
+
+**A:** To run only screenshot tests, you can configure your project with the following:
+
+```groovy
+android {
+    testOptions {
+        unitTests {
+            all {
+                // -Pscreenshot to filter screenshot tests
+                it.useJUnit {
+                    if (project.hasProperty("screenshot")) {
+                        includeCategories("io.github.takahirom.roborazzi.testing.category.ScreenshotTests")
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+Include the `-Pscreenshot` property, and only the screenshot tests will be run.
+
+Note: This feature is not provided in the Roborazzi library itself, to keep it simple and utilize JUnit's built-in features for test filtering.
+
+You can also annotate your tests like this:
+
+```kotlin
+/**
+ * You can filter ScreenshotTests using -Pscreenshot parameter
+ */
+interface ScreenshotTests
+
+@Test
+@Category(ScreenshotTests::class)
+fun checkLaunchShot() {
+  onRoot().captureRoboImage(roborazziOptions = roborazziOptions)
+}
+```
+
+This allows you to create a category of screenshot tests and filter them using the `-Pscreenshot` property, thus making it easier to run only those specific tests.
+
+### Q: How can I debug screenshot tests in Android Studio?
+### Q: How can I execute screenshot tests using Android Studio's Run button?
+
+A: To execute screenshot tests using Android Studio's Run button, configure your project as follows:
+
+`gradle.properties`
+
+```groovy
+roborazzi.test.record=true
+```
+
+After that, you can execute screenshot tests using either Android Studio's Run or Debug button as you normally would.
+
+### Q: My screenshot tests are not capturing images. What could be the issue?
+
+**A:** If your screenshot tests are not capturing images, there may be several patterns that are causing this issue. Please follow these troubleshooting steps:
+
+- **Enable Debugging**: Set `ROBORAZZI_DEBUG = true` to see logs.
+- **Check Plugin**: Ensure that the plugin is properly applied.
+- **Run Task**: Verify that the `recordRoborazziDebug` task is running.
+- **Call Method**: Confirm that `captureRoboImage()` is being called.
+
+By following these steps, you should be able to identify and resolve the issue causing the screenshot tests to not capture images.
+
+### Q: I'm seeing an optimization warning related to Java lambdas in Gradle. What can I do?
+
+**A:** This warning may occur with Gradle 7.5. Upgrade to Gradle 7.6.2 to resolve this issue. Change the distribution URL in `gradle-wrapper.properties`:
+
+```diff
+-distributionUrl=https\://services.gradle.org/distributions/gradle-7.5-bin.zip
++distributionUrl=https\://services.gradle.org/distributions/gradle-7.6.2-bin.zip
+```
+
+### Q: Can I run Roborazzi with Bazel?
+
+**A:** As of now, there is no direct support for running Roborazzi with Bazel. However, it is possible to do so. Please refer to the following comment for more details:
+[Roborazzi Bazel Support Comment](https://github.com/takahirom/roborazzi/issues/63#issuecomment-1531990825)
+
+### Q: My tests are being skipped or, conversely, are being run when they should be skipped. How can I handle caching to address this?
+
+**A:** The behavior you are experiencing may be related to caching issues. Although it's
+experimental, you can set the `outputDir` parameter in your `build.gradle` file to handle caching
+and improve the stability of your tests. This parameter allows you to specify the output directory
+for your screenshots, which can help in managing the cache. Here is how you can set it up:
+If you use the default output directory(module/build/outputs/roborazzi), specifying the `outputDir`
+parameter is not necessary. For more reference, you can check
+out [the issue](https://github.com/takahirom/roborazzi/issues/193#issuecomment-1782073746).
+
+```gradle
+roborazzi {
+    outputDir = "src/your/screenshot/folder"
+}
+```