Modernize developer guide demos and snippets

.github/scripts/compare-animation-screenshots.sh

@@ -2,94 +2,6 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
-BASELINE_DIR="${BASELINE_DIR:-${PROJECT_ROOT}/docs/developer-guide/img}"
-STORAGE_DIR="${CN1_STORAGE_DIR:-${HOME}/.cn1}"
-ARTIFACT_DIR="${1:-${PROJECT_ROOT}/docs/demos/animation-screenshot-artifacts}"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
 
-if ! command -v compare >/dev/null 2>&1; then
-  echo "ImageMagick 'compare' command is required." >&2
-  exit 2
-fi
-
-mkdir -p "${ARTIFACT_DIR}"
-find "${ARTIFACT_DIR}" -mindepth 1 -delete
-
-if [[ ! -d "${STORAGE_DIR}" ]]; then
-  echo "Storage directory ${STORAGE_DIR} does not exist; nothing to compare."
-  exit 0
-fi
-
-shopt -s nullglob
-mapfile -d '' SCREENSHOTS < <(find "${STORAGE_DIR}" -type f -name '*.png' -print0)
-shopt -u nullglob
-
-if [[ ${#SCREENSHOTS[@]} -eq 0 ]]; then
-  echo "No screenshots found under ${STORAGE_DIR}; nothing to compare."
-  exit 0
-fi
-
-mismatch_count=0
-
-for screenshot in "${SCREENSHOTS[@]}"; do
-  filename="$(basename "${screenshot}")"
-  base="${filename%.png}"
-
-  baseline=""
-  baseline_ext=""
-  for ext in png PNG jpg JPG jpeg JPEG; do
-    candidate="${BASELINE_DIR}/${base}.${ext}"
-    if [[ -f "${candidate}" ]]; then
-      baseline="${candidate}"
-      baseline_ext="${ext}"
-      break
-    fi
-  done
-
-  if [[ -z "${baseline}" ]]; then
-    echo "No baseline found for ${filename}; treating as mismatch." >&2
-    mismatch_count=$((mismatch_count + 1))
-    cp "${screenshot}" "${ARTIFACT_DIR}/${filename}"
-    rm -f "${screenshot}"
-    continue
-  fi
-
-  metric_file="$(mktemp)"
-  diff_image="${ARTIFACT_DIR}/${base}.diff.png"
-
-  set +e
-  compare -metric AE "${screenshot}" "${baseline}" "${diff_image}" 2>"${metric_file}"
-  status=$?
-  set -e
-
-  if [[ ${status} -eq 0 ]]; then
-    rm -f "${screenshot}" "${diff_image}" "${metric_file}"
-    echo "${filename} matches baseline; capture discarded."
-    continue
-  fi
-
-  if [[ ${status} -ne 1 ]]; then
-    cat "${metric_file}" >&2
-    rm -f "${metric_file}" "${diff_image}"
-    echo "ImageMagick comparison failed for ${filename}." >&2
-    exit ${status}
-  fi
-
-  mismatch_count=$((mismatch_count + 1))
-  metric_value="$(cat "${metric_file}")"
-  rm -f "${metric_file}"
-
-  cp "${screenshot}" "${ARTIFACT_DIR}/${filename}"
-  cp "${baseline}" "${ARTIFACT_DIR}/${base}.baseline.${baseline_ext}"
-  echo "${metric_value}" > "${ARTIFACT_DIR}/${base}.metric.txt"
-  rm -f "${screenshot}"
-  echo "${filename} differs from baseline; artifacts stored in ${ARTIFACT_DIR}." >&2
-done
-
-if [[ ${mismatch_count} -eq 0 ]]; then
-  echo "All screenshots match their baselines."
-  exit 0
-fi
-
-echo "${mismatch_count} screenshot(s) differ from the documented baseline." >&2
-exit 1
+exec "${PROJECT_ROOT}/scripts/developer-guide/compare-guide-screenshots.sh" "$@"

.github/workflows/developer-guide-docs.yml

@@ -5,6 +5,7 @@ on:
     paths:
       - 'docs/developer-guide/**'
       - 'docs/demos/**'
+      - 'scripts/developer-guide/**'
       - '.github/workflows/developer-guide-docs.yml'
   release:
     types: [published]
@@ -30,9 +31,14 @@ jobs:
           filters: |
             demos:
               - 'docs/demos/**'
+              - 'scripts/developer-guide/compare-guide-screenshots.sh'
+              - 'scripts/developer-guide/guide-screenshots.txt'
               - '.github/workflows/developer-guide-docs.yml'
             docs:
               - 'docs/developer-guide/**'
+              - 'docs/demos/common/src/main/snippets/**'
+              - 'scripts/developer-guide/migrate-inline-guide-snippets.py'
+              - 'scripts/developer-guide/validate-guide-snippets.py'
               - '.github/workflows/developer-guide-docs.yml'
             workflow:
               - '.github/workflows/developer-guide-docs.yml'
@@ -41,46 +47,63 @@ jobs:
         uses: actions/setup-java@v5
         with:
           distribution: 'temurin'
-          java-version: '11'
+          java-version: '17'
+
+      - name: Install local Codename One Maven artifacts
+        if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
+        run: |
+          set -euo pipefail
+          xvfb-run -a mvn -B -ntp -f maven/pom.xml \
+            -pl core,javase,css-compiler,codenameone-maven-plugin \
+            -am install \
+            -Plocal-dev-javase \
+            -DskipTests \
+            -Dmaven.javadoc.skip=true
 
       - name: Build Codename One demos
-        if: github.event_name != 'pull_request' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
+        if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
         run: |
           set -euo pipefail
           mkdir -p "$HOME/.codenameone"
           touch "$HOME/.codenameone/guibuilder.jar"
           cp maven/CodeNameOneBuildClient.jar "$HOME/.codenameone/CodeNameOneBuildClient.jar"
-          xvfb-run -a mvn -B -ntp -Dgenerate-gui-sources-done=true -pl common -am -f docs/demos/pom.xml install
+          xvfb-run -a mvn -B -ntp -Dgenerate-gui-sources-done=true -Dcodename1.platform=javase -f docs/demos/pom.xml test
+
+      - name: Validate developer guide snippets
+        if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
+        run: |
+          set -euo pipefail
+          python3 scripts/developer-guide/validate-guide-snippets.py
 
       - name: Install ImageMagick for screenshot comparison
-        if: github.event_name != 'pull_request' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
+        if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
         run: |
           set -euo pipefail
           sudo apt-get update
           sudo apt-get install -y --no-install-recommends imagemagick
 
-      - name: Compare animation screenshots
-        id: compare_animation_screenshots
-        if: github.event_name != 'pull_request' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
+      - name: Compare guide screenshots
+        id: compare_guide_screenshots
+        if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
         continue-on-error: true
         run: |
           set -euo pipefail
-          ARTIFACT_DIR="build/developer-guide/animation-screenshots"
+          ARTIFACT_DIR="build/developer-guide/guide-screenshots"
           mkdir -p "${ARTIFACT_DIR}"
-          .github/scripts/compare-animation-screenshots.sh "${ARTIFACT_DIR}"
+          scripts/developer-guide/compare-guide-screenshots.sh "${ARTIFACT_DIR}"
 
-      - name: Upload animation screenshot mismatches
-        if: steps.compare_animation_screenshots.outcome == 'failure'
+      - name: Upload guide screenshot mismatches
+        if: steps.compare_guide_screenshots.outcome == 'failure'
         uses: actions/upload-artifact@v7
         with:
-          name: developer-guide-animation-screenshots
-          path: build/developer-guide/animation-screenshots
+          name: developer-guide-screenshots
+          path: build/developer-guide/guide-screenshots
           if-no-files-found: warn
 
-      - name: Fail when animation screenshots differ
-        if: steps.compare_animation_screenshots.outcome == 'failure'
+      - name: Fail when guide screenshots differ
+        if: steps.compare_guide_screenshots.outcome == 'failure'
         run: |
-          echo "Animation demo screenshots differ from developer guide assets." >&2
+          echo "Generated guide screenshots differ from developer guide assets." >&2
           exit 1
 
       - name: Determine publication metadata
@@ -407,7 +430,7 @@ jobs:
           if-no-files-found: warn
 
       - name: Upload AsciiDoc linter report
-        if: always()
+        if: always() && env.ASCII_DOC_LINT_REPORT != ''
         uses: actions/upload-artifact@v7
         with:
           name: developer-guide-asciidoc-lint
@@ -435,15 +458,15 @@ jobs:
           if-no-files-found: warn
 
       - name: Upload paragraph capitalization report
-        if: always()
+        if: always() && env.PARAGRAPH_CAP_REPORT != ''
         uses: actions/upload-artifact@v7
         with:
           name: developer-guide-paragraph-capitalization
           path: ${{ env.PARAGRAPH_CAP_REPORT }}
           if-no-files-found: warn
 
       - name: Upload LanguageTool report
-        if: always()
+        if: always() && env.LANGUAGETOOL_REPORT != ''
         uses: actions/upload-artifact@v7
         with:
           name: developer-guide-languagetool

docs/demos/android/pom.xml

@@ -14,8 +14,8 @@
 
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <maven.compiler.source>1.8</maven.compiler.source>
-    <maven.compiler.target>1.8</maven.compiler.target>
+    <maven.compiler.source>17</maven.compiler.source>
+    <maven.compiler.target>17</maven.compiler.target>
     <codename1.platform>android</codename1.platform>
       <codename1.projectPlatform>android</codename1.projectPlatform>
       <codename1.defaultBuildTarget>android-device</codename1.defaultBuildTarget>

docs/demos/common/codenameone_settings.properties

@@ -2,7 +2,7 @@ codename1.android.keystore=
 codename1.android.keystoreAlias=
 codename1.android.keystorePassword=
 codename1.arg.ios.newStorageLocation=true
-codename1.arg.java.version=8
+codename1.arg.java.version=17
 codename1.displayName=DemoCode
 codename1.icon=icon.png
 codename1.ios.appid=Q5GHSKAL2F.com.codenameone.developerguide

docs/demos/common/pom.xml

@@ -305,8 +305,8 @@
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
                 <configuration>
-                    <source>1.8</source>
-                    <target>1.8</target>
+                    <source>${maven.compiler.source}</source>
+                    <target>${maven.compiler.target}</target>
                 </configuration>
             </plugin>
             <plugin>

docs/demos/common/src/main/java/com/codenameone/developerguide/DemoRegistry.java

@@ -37,6 +37,14 @@ public final class DemoRegistry {
                     new SwipeBackSupportDemo()
             )
     );
+    private static final List<GuideScreenshot> SCREENSHOTS = Collections.unmodifiableList(
+            Arrays.asList(
+                    screenshot("layout-animations", "Layout Animations", "layout-animation-1.png"),
+                    screenshot("slide-transitions", "Slide Transitions", "transition-slide.png"),
+                    screenshot("bubble-transition", "Bubble Transition", "transition-bubble.png"),
+                    screenshot("morph-transition", "Morph Transition", "mighty-morphing-components-1.png")
+            )
+    );
 
     private DemoRegistry() {
         // utility class
@@ -45,4 +53,17 @@ private DemoRegistry() {
     public static List<Demo> getDemos() {
         return DEMOS;
     }
+
+    public static List<GuideScreenshot> getScreenshots() {
+        return SCREENSHOTS;
+    }
+
+    private static GuideScreenshot screenshot(String id, String demoTitle, String fileName) {
+        for (Demo demo : DEMOS) {
+            if (demo.getTitle().equals(demoTitle)) {
+                return new GuideScreenshot(id, demo, fileName);
+            }
+        }
+        throw new IllegalStateException("No guide demo registered with title: " + demoTitle);
+    }
 }

docs/demos/common/src/main/java/com/codenameone/developerguide/GuideScreenshot.java

@@ -0,0 +1,28 @@
+package com.codenameone.developerguide;
+
+/**
+ * Stable mapping between a runnable guide demo and the image it documents.
+ */
+public final class GuideScreenshot {
+    private final String id;
+    private final Demo demo;
+    private final String fileName;
+
+    public GuideScreenshot(String id, Demo demo, String fileName) {
+        this.id = id;
+        this.demo = demo;
+        this.fileName = fileName;
+    }
+
+    public String getId() {
+        return id;
+    }
+
+    public Demo getDemo() {
+        return demo;
+    }
+
+    public String getFileName() {
+        return fileName;
+    }
+}

docs/demos/common/src/main/snippets/developer-guide/3d-graphics.java

@@ -0,0 +1,71 @@
+// Generated from docs/developer-guide source blocks. Edit the guide snippets here, not inline.
+
+// tag::3d-graphics-java-001[]
+RenderView view = new RenderView(new Renderer() {
+    private final Camera camera = new Camera();
+    private Mesh cube;
+    private Material material;
+    private float angle;
+
+    public void onInit(GraphicsDevice device) {
+        cube = Primitives.cube(device, 1.5f);
+        material = new Material(Material.Type.PHONG)
+                .setColor(0xff3366ff)
+                .setShininess(24f);
+        camera.setPerspective(45f, 0.1f, 100f)
+              .setPosition(2.5f, 2f, 3.5f)
+              .setTarget(0f, 0f, 0f);
+        device.setLight(new Light().setDirection(-0.4f, -1f, -0.6f));
+    }
+
+    public void onResize(GraphicsDevice device, int w, int h) {
+        camera.setAspect((float) w / Math.max(1, h));
+        device.setViewport(0, 0, w, h);
+    }
+
+    public void onFrame(GraphicsDevice device) {
+        angle += 0.02f;
+        device.clear(0xff101018, true, true);
+        device.setCamera(camera);
+        device.draw(cube, material, Matrix4.rotation(angle, 0.3f, 1f, 0.1f));
+    }
+
+    public void onDispose(GraphicsDevice device) {
+    }
+});
+view.setContinuous(true);            // animate; omit for on-demand rendering
+
+Form hi = new Form("3D", new BorderLayout());
+hi.add(BorderLayout.CENTER, view);
+hi.show();
+// end::3d-graphics-java-001[]
+
+// tag::3d-graphics-java-002[]
+Texture tex = device.createTexture(myImage);     // or createTexture(w, h, argb)
+tex.setFilter(Texture.Filter.LINEAR).setWrap(Texture.Wrap.REPEAT);
+Material m = new Material(Material.Type.UNLIT).setTexture(tex);
+// end::3d-graphics-java-002[]
+
+// tag::3d-graphics-java-003[]
+VertexBuffer vb = device.createVertexBuffer(VertexFormat.POSITION_NORMAL_TEXCOORD, 4);
+vb.setData(new float[] { /* px,py,pz, nx,ny,nz, u,v  per vertex ... */ });
+IndexBuffer ib = device.createIndexBuffer(6);
+ib.setData(new int[] { 0, 1, 2, 0, 2, 3 });
+Mesh mesh = new Mesh(vb, ib, PrimitiveType.TRIANGLES);
+// end::3d-graphics-java-003[]
+
+// tag::3d-graphics-java-004[]
+InputStream in = Display.getInstance().getResourceAsStream(getClass(), "/boombox.glb");
+GltfLoader.GltfModel loaded = GltfLoader.loadModel(device, in);
+Material material = new Material(Material.Type.PHONG).setShininess(16f);
+if (loaded.getBaseColorTexture() != null) {
+    material.setTexture(loaded.getBaseColorTexture());
+}
+Mesh model = loaded.getMesh();           // draw it like any other mesh
+// end::3d-graphics-java-004[]
+
+// tag::3d-graphics-java-005[]
+if (CN.isGpuSupported()) {
+    // GraphicsDevice.getCapabilities() exposes max texture size, shader level, etc.
+}
+// end::3d-graphics-java-005[]