Skip to content

Commit b957748

Browse files
Katia Arestikaresti
Katia Aresti
authored and
karesti
committed
Poc Guides
1 parent 31c7e9d commit b957748

12 files changed

Lines changed: 851 additions & 0 deletions

File tree

‎.github/workflows/guides.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: Notify Website of Guide Changes
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- '**/guide.adoc'
8+
- 'docs-maven-plugin/**'
9+
10+
jobs:
11+
notify-website:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Trigger website rebuild
15+
run: |
16+
curl -X POST \
17+
-H "Accept: application/vnd.github+json" \
18+
-H "Authorization: Bearer ${{ secrets.WEBSITE_DISPATCH_TOKEN }}" \
19+
https://api.github.com/repos/infinispan/infinispan.github.io/dispatches \
20+
-d '{"event_type":"guides_updated"}'

‎docs-maven-plugin/pom.xml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<modelVersion>4.0.0</modelVersion>
6+
7+
<groupId>org.infinispan.tutorial.simple</groupId>
8+
<artifactId>docs-maven-plugin</artifactId>
9+
<version>16.1.3</version>
10+
<packaging>jar</packaging>
11+
12+
<properties>
13+
<maven.compiler.source>17</maven.compiler.source>
14+
<maven.compiler.target>17</maven.compiler.target>
15+
<maven.compiler.release>17</maven.compiler.release>
16+
<asciidoctorj.version>3.0.1</asciidoctorj.version>
17+
<jackson.version>2.18.3</jackson.version>
18+
</properties>
19+
20+
<dependencies>
21+
<dependency>
22+
<groupId>org.asciidoctor</groupId>
23+
<artifactId>asciidoctorj</artifactId>
24+
<version>${asciidoctorj.version}</version>
25+
</dependency>
26+
<dependency>
27+
<groupId>com.fasterxml.jackson.core</groupId>
28+
<artifactId>jackson-databind</artifactId>
29+
<version>${jackson.version}</version>
30+
</dependency>
31+
<dependency>
32+
<groupId>com.fasterxml.jackson.dataformat</groupId>
33+
<artifactId>jackson-dataformat-yaml</artifactId>
34+
<version>${jackson.version}</version>
35+
</dependency>
36+
<dependency>
37+
<groupId>org.junit.jupiter</groupId>
38+
<artifactId>junit-jupiter</artifactId>
39+
<version>${version.junit6}</version>
40+
<scope>test</scope>
41+
</dependency>
42+
</dependencies>
43+
44+
<build>
45+
<plugins>
46+
<plugin>
47+
<groupId>org.codehaus.mojo</groupId>
48+
<artifactId>exec-maven-plugin</artifactId>
49+
<executions>
50+
<execution>
51+
<id>generate-guide-metadata</id>
52+
<phase>package</phase>
53+
<goals>
54+
<goal>java</goal>
55+
</goals>
56+
<configuration>
57+
<mainClass>org.infinispan.tutorial.docs.GuideMetadataGenerator</mainClass>
58+
<arguments>
59+
<argument>${project.basedir}/..</argument>
60+
<argument>${project.basedir}/../target/guides</argument>
61+
</arguments>
62+
</configuration>
63+
</execution>
64+
</executions>
65+
</plugin>
66+
</plugins>
67+
</build>
68+
</project>

‎docs-maven-plugin/src/main/java/org/infinispan/tutorial/docs/GuideMetadataGenerator.java‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
package org.infinispan.tutorial.docs;
2+
3+
import java.io.IOException;
4+
import java.nio.file.Files;
5+
import java.nio.file.Path;
6+
import java.util.ArrayList;
7+
import java.util.Arrays;
8+
import java.util.Comparator;
9+
import java.util.LinkedHashMap;
10+
import java.util.List;
11+
import java.util.Map;
12+
import java.util.Set;
13+
import java.util.stream.Stream;
14+
15+
import org.asciidoctor.Asciidoctor;
16+
import org.asciidoctor.Options;
17+
import org.asciidoctor.SafeMode;
18+
import org.asciidoctor.ast.Document;
19+
20+
import com.fasterxml.jackson.annotation.JsonInclude;
21+
import com.fasterxml.jackson.databind.ObjectMapper;
22+
import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
23+
import com.fasterxml.jackson.dataformat.yaml.YAMLGenerator;
24+
25+
public class GuideMetadataGenerator {
26+
27+
private static final Set<String> SKIP_DIRS = Set.of(
28+
"target", "docs", "documentation", "docs-maven-plugin", "non-java-clients", ".git", ".github");
29+
30+
private final Path srcDir;
31+
private final Path outputDir;
32+
33+
public GuideMetadataGenerator(Path srcDir, Path outputDir) {
34+
this.srcDir = srcDir;
35+
this.outputDir = outputDir;
36+
}
37+
38+
public static void main(String[] args) throws Exception {
39+
if (args.length < 2) {
40+
System.err.println("Usage: GuideMetadataGenerator <srcDir> <outputDir>");
41+
System.exit(1);
42+
}
43+
Path src = Path.of(args[0]);
44+
Path out = Path.of(args[1]);
45+
System.out.println("[INFO] Scanning for guides in: " + src);
46+
GuideMetadataGenerator generator = new GuideMetadataGenerator(src, out);
47+
generator.generate();
48+
System.out.println("[INFO] Guide metadata written to: " + out);
49+
}
50+
51+
public void generate() throws IOException {
52+
List<Map<String, Object>> guides = new ArrayList<>();
53+
Path guidesOutputDir = outputDir.resolve("guides");
54+
Files.createDirectories(guidesOutputDir);
55+
56+
Options options = Options.builder()
57+
.safe(SafeMode.UNSAFE)
58+
.build();
59+
60+
try (Asciidoctor asciidoctor = Asciidoctor.Factory.create()) {
61+
collectGuides(srcDir, "", asciidoctor, options, guides, guidesOutputDir);
62+
}
63+
64+
guides.sort(Comparator.comparing(g -> (String) g.get("id")));
65+
66+
Map<String, Object> index = new LinkedHashMap<>();
67+
index.put("guides", guides);
68+
69+
ObjectMapper om = new ObjectMapper(
70+
new YAMLFactory()
71+
.enable(YAMLGenerator.Feature.MINIMIZE_QUOTES)
72+
.disable(YAMLGenerator.Feature.SPLIT_LINES)
73+
.disable(YAMLGenerator.Feature.WRITE_DOC_START_MARKER));
74+
om.setSerializationInclusion(JsonInclude.Include.NON_EMPTY);
75+
76+
Files.createDirectories(outputDir);
77+
om.writeValue(outputDir.resolve("index.yaml").toFile(), index);
78+
}
79+
80+
private void collectGuides(Path dir, String prefix, Asciidoctor asciidoctor,
81+
Options options, List<Map<String, Object>> guides, Path guidesOutputDir)
82+
throws IOException {
83+
try (Stream<Path> entries = Files.list(dir)) {
84+
List<Path> sorted = entries.sorted().toList();
85+
for (Path entry : sorted) {
86+
if (!Files.isDirectory(entry)) {
87+
continue;
88+
}
89+
String name = entry.getFileName().toString();
90+
if (name.startsWith(".") || SKIP_DIRS.contains(name)) {
91+
continue;
92+
}
93+
Path guideFile = entry.resolve("guide.adoc");
94+
String dirName = stripPrefix(entry.getFileName().toString());
95+
if (Files.exists(guideFile)) {
96+
String id = prefix.isEmpty() ? dirName : prefix + "-" + dirName;
97+
processGuide(guideFile, id, asciidoctor, options, guides, guidesOutputDir);
98+
}
99+
String subPrefix = prefix.isEmpty() ? dirName : prefix + "-" + dirName;
100+
collectGuides(entry, subPrefix, asciidoctor, options, guides, guidesOutputDir);
101+
}
102+
}
103+
}
104+
105+
private String stripPrefix(String dirName) {
106+
if (dirName.startsWith("infinispan-")) {
107+
return dirName.substring("infinispan-".length());
108+
}
109+
return dirName;
110+
}
111+
112+
private void processGuide(Path guideFile, String id, Asciidoctor asciidoctor,
113+
Options options, List<Map<String, Object>> guides, Path guidesOutputDir)
114+
throws IOException {
115+
String content = Files.readString(guideFile);
116+
Document doc = asciidoctor.load(content, options);
117+
118+
Map<String, Object> guide = new LinkedHashMap<>();
119+
guide.put("id", id);
120+
guide.put("title", doc.getDoctitle());
121+
guide.put("summary", attrString(doc, "summary"));
122+
guide.put("mode", attrString(doc, "mode"));
123+
guide.put("topics", splitComma(attrString(doc, "topics")));
124+
guide.put("keywords", splitComma(attrString(doc, "keywords")));
125+
guide.put("source-dir", attrString(doc, "source-dir"));
126+
guide.put("file", id + ".adoc");
127+
128+
String duration = attrString(doc, "duration");
129+
if (duration != null) {
130+
try {
131+
guide.put("duration", Integer.parseInt(duration));
132+
} catch (NumberFormatException e) {
133+
guide.put("duration", duration);
134+
}
135+
}
136+
137+
guides.add(guide);
138+
Files.copy(guideFile, guidesOutputDir.resolve(id + ".adoc"));
139+
}
140+
141+
private String attrString(Document doc, String name) {
142+
Object val = doc.getAttribute(name);
143+
return val != null ? val.toString() : null;
144+
}
145+
146+
private List<String> splitComma(String value) {
147+
if (value == null || value.isBlank()) {
148+
return List.of();
149+
}
150+
return Arrays.stream(value.split(","))
151+
.map(String::trim)
152+
.filter(s -> !s.isEmpty())
153+
.toList();
154+
}
155+
}

‎docs-maven-plugin/src/test/java/org/infinispan/tutorial/docs/GuideMetadataGeneratorTest.java‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
package org.infinispan.tutorial.docs;
2+
3+
import static org.junit.jupiter.api.Assertions.*;
4+
5+
import java.nio.file.Files;
6+
import java.nio.file.Path;
7+
import java.util.List;
8+
import java.util.Map;
9+
10+
import org.junit.jupiter.api.Test;
11+
import org.junit.jupiter.api.io.TempDir;
12+
13+
class GuideMetadataGeneratorTest {
14+
15+
@TempDir
16+
Path outputDir;
17+
18+
@Test
19+
void generatesIndexFromGuideFiles() throws Exception {
20+
Path srcDir = Path.of(getClass().getClassLoader()
21+
.getResource("test-tutorials").toURI());
22+
23+
GuideMetadataGenerator generator = new GuideMetadataGenerator(srcDir, outputDir);
24+
generator.generate();
25+
26+
Path indexFile = outputDir.resolve("index.yaml");
27+
assertTrue(Files.exists(indexFile), "index.yaml should be created");
28+
29+
String yaml = Files.readString(indexFile);
30+
assertTrue(yaml.contains("Remote Cache Tutorial"), "should contain tutorial-a title");
31+
assertTrue(yaml.contains("Distributed Cache Tutorial"), "should contain tutorial-b title");
32+
assertTrue(yaml.contains("mode: remote"), "should contain mode attribute");
33+
assertTrue(yaml.contains("mode: embedded"), "should contain mode attribute");
34+
assertTrue(yaml.contains("caching"), "should contain topic");
35+
}
36+
37+
@Test
38+
void copiesGuideFilesToOutput() throws Exception {
39+
Path srcDir = Path.of(getClass().getClassLoader()
40+
.getResource("test-tutorials").toURI());
41+
42+
GuideMetadataGenerator generator = new GuideMetadataGenerator(srcDir, outputDir);
43+
generator.generate();
44+
45+
Path guidesDir = outputDir.resolve("guides");
46+
assertTrue(Files.exists(guidesDir), "guides/ directory should be created");
47+
assertTrue(Files.list(guidesDir).count() >= 2, "should copy at least 2 guide files");
48+
}
49+
50+
@Test
51+
void derivesIdFromDirectoryPath() throws Exception {
52+
Path srcDir = Path.of(getClass().getClassLoader()
53+
.getResource("test-tutorials").toURI());
54+
55+
GuideMetadataGenerator generator = new GuideMetadataGenerator(srcDir, outputDir);
56+
generator.generate();
57+
58+
String yaml = Files.readString(outputDir.resolve("index.yaml"));
59+
assertTrue(yaml.contains("id: remote-cache"), "should derive id: infinispan-remote/cache -> remote-cache");
60+
assertTrue(yaml.contains("id: embedded-cache-distributed"), "should derive id: infinispan-embedded/cache-distributed -> embedded-cache-distributed");
61+
}
62+
63+
@Test
64+
void skipsDirectoriesWithoutGuide() throws Exception {
65+
Path srcDir = Path.of(getClass().getClassLoader()
66+
.getResource("test-tutorials").toURI());
67+
Path noGuideDir = srcDir.resolve("no-guide-here");
68+
Files.createDirectories(noGuideDir);
69+
70+
GuideMetadataGenerator generator = new GuideMetadataGenerator(srcDir, outputDir);
71+
generator.generate();
72+
73+
String yaml = Files.readString(outputDir.resolve("index.yaml"));
74+
assertFalse(yaml.contains("no-guide-here"), "should skip dirs without guide.adoc");
75+
76+
Files.delete(noGuideDir);
77+
}
78+
}

‎docs-maven-plugin/src/test/resources/test-tutorials/infinispan-embedded/cache-distributed/guide.adoc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
= Distributed Cache Tutorial
2+
:summary: Create a distributed cache across a cluster of Infinispan nodes
3+
:mode: embedded
4+
:topics: caching,clustering
5+
:keywords: distributed,cluster,embedded
6+
:duration: 10
7+
:source-dir: infinispan-embedded/cache-distributed
8+
9+
== Prerequisites
10+
11+
* Java 17+
12+
13+
== Steps
14+
15+
Create a clustered cache manager.

‎docs-maven-plugin/src/test/resources/test-tutorials/infinispan-remote/cache/guide.adoc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
= Remote Cache Tutorial
2+
:summary: Learn how to connect to Infinispan Server and perform cache operations
3+
:mode: remote
4+
:topics: caching,getting-started
5+
:keywords: cache,put,get,remove,client
6+
:duration: 10
7+
:source-dir: infinispan-remote/cache
8+
9+
== Prerequisites
10+
11+
* Infinispan Server running
12+
13+
== Steps
14+
15+
Put and get a value.

0 commit comments

Comments
 (0)