Merge remote-tracking branch 'origin/main' into takahirom/roborazzi-t…

…ask-type-property-to-roborazzi-options/2023-11-13

.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: docs/roborazzi-docs
+    ARTIFACT: webHelpROBORAZZI-DOCS2-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,7 @@
+<!-- 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 +43,11 @@ 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 +218,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 +234,11 @@ 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,10 +978,10 @@ 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
+```
 roborazzi.test.record=true
 # roborazzi.test.compare=true
 # roborazzi.test.verify=true
@@ -981,15 +993,15 @@ roborazzi.test.record=true
 
 This option lets you set the resize scale for the image being recorded. The default value is 1.0.
 
-```properties
+```
 roborazzi.record.resizeScale=0.5
 ```
 
 #### roborazzi.record.filePathStrategy
 
 This setting allows you to specify the file path strategy for the recorded image. The default strategy is `relativePathFromCurrentDirectory`. If you choose `relativePathFromRoborazziContextOutputDirectory`, the file will be saved in the output directory specified by `RoborazziRule.Options.outputDirectoryPath`.
 
-```properties
+```
 roborazzi.record.filePathStrategy=relativePathFromRoborazziContextOutputDirectory
 ```
 
@@ -1001,10 +1013,14 @@ This option enables you to define the naming strategy for the recorded image. Th
 - If you choose `escapedTestPackageAndClassAndMethod`, the file name will be `com_example_MyTest.testMethod.png`.
 - If you choose `testClassAndMethod`, the file name will be `MyTest.testMethod.png`.
 
-```properties
+```
 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?
@@ -1077,9 +1093,8 @@ By following these steps, you should be able to identify and resolve the issue c
 
 **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
+```
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.6.2-bin.zip
 ```
 
 ### Q: Can I run Roborazzi with Bazel?
@@ -1102,6 +1117,7 @@ roborazzi {
     outputDir = "src/your/screenshot/folder"
 }
 ```
+</div>
 
 ### LICENSE
 

README.template.md

@@ -0,0 +1,29 @@
+<!-- Generated by ./gradlew generateReadme. Do not edit this file. -->
+<div name="topic_top">
+</div>
+<div name="topic_try_it_out">
+</div>
+<div name="topic_how_to_use">
+</div>
+<div name="topic_faq">
+</div>
+
+### LICENSE
+
+```
+Copyright 2023 takahirom
+Copyright 2019 Square, Inc.
+Copyright The Android Open Source Project
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the 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,49 @@ 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 readmeTemplate = rootProject.file("README.template.md")
+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 = readmeTemplate.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\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,14 @@
+<?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>
+        <product-web-url>https://github.com/takahirom/roborazzi</product-web-url>
+        <enable-browser-edits>true</enable-browser-edits>
+        <header-logo>dot.png</header-logo>
+        <primary-color>blueberry</primary-color>
+        <browser-edits-url>https://github.com/takahirom/roborazzi/edit/main/docs/</browser-edits-url>
+    </variables>
+    <footer>
+        <link href="https://github.com/takahirom/roborazzi">GitHub</link>
+    </footer>
+</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"
+                 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>