diff --git a/train-docs/pom.xml b/train-docs/pom.xml index c37a007..958b8f3 100644 --- a/train-docs/pom.xml +++ b/train-docs/pom.xml @@ -18,8 +18,9 @@ 3.6.3 - 1.4.2 + 1.4.1 4.0.6 + 2.1.0 @@ -40,6 +41,27 @@ org.apache.maven maven-settings-builder ${maven.version} + + + org.codehaus.plexus + plexus-utils + + + + + org.apache.maven + maven-embedder + ${maven.version} + + + org.codehaus.plexus + * + + + org.sonatype.plexus + * + + org.apache.maven.resolver @@ -51,6 +73,11 @@ maven-resolver-impl ${maven.resolver.version} + + org.apache.maven.resolver + maven-resolver-util + ${maven.resolver.version} + org.apache.maven.resolver maven-resolver-transport-file @@ -89,6 +116,18 @@ docs + + org.apache.maven.plugins + maven-surefire-plugin + + + ${maven.multiModuleProjectDirectory}/spring-cloud-dependencies/pom.xml + ${maven-deploy-plugin.deployZipUrl} + ${project.build.directory}/unpacked-docs/ + ${project.build.directory}/train-docs/ + + + pl.project13.maven git-commit-id-plugin @@ -102,10 +141,38 @@ org.codehaus.mojo exec-maven-plugin + + org.asciidoctor asciidoctor-maven-plugin + + ${project.build.directory}/train-docs/ + + ${project.build.directory}/unpacked-docs/ + + maven-antrun-plugin diff --git a/train-docs/src/main/java/org/springframework/cloud/internal/ArtifactFetcher.java b/train-docs/src/main/java/org/springframework/cloud/internal/ArtifactFetcher.java new file mode 100644 index 0000000..4bfad36 --- /dev/null +++ b/train-docs/src/main/java/org/springframework/cloud/internal/ArtifactFetcher.java @@ -0,0 +1,155 @@ +/* + * Copyright 2013-2020 the original author or authors. + * + * 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 + * + * https://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. + */ + +package org.springframework.cloud.internal; + +import java.io.File; +import java.net.URI; +import java.util.Collections; +import java.util.List; + +import org.apache.maven.repository.internal.MavenRepositorySystemUtils; +import org.apache.maven.settings.Settings; +import org.apache.maven.settings.building.DefaultSettingsBuilderFactory; +import org.apache.maven.settings.building.DefaultSettingsBuildingRequest; +import org.apache.maven.settings.building.SettingsBuilder; +import org.apache.maven.settings.building.SettingsBuildingException; +import org.apache.maven.settings.building.SettingsBuildingRequest; +import org.apache.maven.settings.building.SettingsBuildingResult; +import org.eclipse.aether.DefaultRepositorySystemSession; +import org.eclipse.aether.RepositorySystem; +import org.eclipse.aether.RepositorySystemSession; +import org.eclipse.aether.artifact.Artifact; +import org.eclipse.aether.artifact.DefaultArtifact; +import org.eclipse.aether.connector.basic.BasicRepositoryConnectorFactory; +import org.eclipse.aether.impl.DefaultServiceLocator; +import org.eclipse.aether.repository.LocalRepository; +import org.eclipse.aether.repository.RemoteRepository; +import org.eclipse.aether.repository.RepositoryPolicy; +import org.eclipse.aether.resolution.ArtifactRequest; +import org.eclipse.aether.resolution.ArtifactResult; +import org.eclipse.aether.spi.connector.RepositoryConnectorFactory; +import org.eclipse.aether.spi.connector.transport.TransporterFactory; +import org.eclipse.aether.transport.file.FileTransporterFactory; +import org.eclipse.aether.transport.http.HttpTransporterFactory; + +import org.springframework.util.StringUtils; + +import static org.springframework.cloud.internal.Logger.info; + +class ArtifactFetcher { + + private final File outputFolder; + + private final RepositorySystem repositorySystem; + + private final RepositorySystemSession session; + + private final List remoteRepository; + + ArtifactFetcher(File outputFolder, String url) { + this.outputFolder = outputFolder; + this.repositorySystem = newRepositorySystem(); + this.session = newSession(this.repositorySystem); + this.remoteRepository = Collections.singletonList( + new RemoteRepository.Builder("remote", "default", url).build()); + } + + File unpackedDocs(Project project) { + String artifactName = project.name; + String version = project.version; + try { + Artifact artifact = new DefaultArtifact("org.springframework.cloud", + artifactName, "sources", "jar", version); + ArtifactRequest request = new ArtifactRequest(artifact, this.remoteRepository, + null); + info(artifactName + ": Resolving artifact [" + artifact + + "] using remote repositories " + this.remoteRepository); + ArtifactResult result = this.repositorySystem.resolveArtifact(this.session, + request); + info(artifactName + ": Resolved artifact [" + artifact + "] to " + + result.getArtifact().getFile()); + File unpackedDoc = unpackDoc(artifactName, + result.getArtifact().getFile().toURI()); + info(artifactName + ": Unpacked file to [" + unpackedDoc.getAbsolutePath() + + "]"); + return unpackedDoc; + } + catch (IllegalStateException ise) { + throw ise; + } + catch (Exception e) { + // throw new IllegalStateException( + System.err.println( + "Exception occurred while trying to download an artifact with name [" + + artifactName + "] and version [" + version + + "] in remote repo [" + this.remoteRepository); + // ,e); + return null; + } + } + + private File unpackDoc(String artifactName, URI stubJarUri) { + File unzippedDocs = new File(outputFolder, artifactName); + unzippedDocs.mkdirs(); + info(artifactName + ": Unpacking stub from JAR [URI: " + stubJarUri + "]"); + ZipCategory.unzipTo(new File(stubJarUri), unzippedDocs); + return unzippedDocs; + } + + private RepositorySystem newRepositorySystem() { + DefaultServiceLocator locator = MavenRepositorySystemUtils.newServiceLocator(); + locator.addService(RepositoryConnectorFactory.class, + BasicRepositoryConnectorFactory.class); + locator.addService(TransporterFactory.class, FileTransporterFactory.class); + locator.addService(TransporterFactory.class, HttpTransporterFactory.class); + return locator.getService(RepositorySystem.class); + } + + private RepositorySystemSession newSession(RepositorySystem system) { + DefaultRepositorySystemSession session = MavenRepositorySystemUtils.newSession(); + session.setUpdatePolicy(RepositoryPolicy.UPDATE_POLICY_ALWAYS); + session.setChecksumPolicy(RepositoryPolicy.CHECKSUM_POLICY_WARN); + String localRepository = settings().getLocalRepository(); + localRepository = StringUtils.hasText(localRepository) ? localRepository + : System.getProperty("user.home") + File.separator + ".m2" + + File.separator + "repository"; + LocalRepository localRepo = new LocalRepository(localRepository); + session.setLocalRepositoryManager( + system.newLocalRepositoryManager(session, localRepo)); + return session; + } + + private static Settings settings() { + SettingsBuilder builder = new DefaultSettingsBuilderFactory().newInstance(); + SettingsBuildingRequest request = new DefaultSettingsBuildingRequest(); + request.setUserSettingsFile(userSettings()); + SettingsBuildingResult result; + try { + result = builder.build(request); + } + catch (SettingsBuildingException ex) { + throw new IllegalStateException(ex); + } + return result.getEffectiveSettings(); + } + + private static File userSettings() { + return new File(new File(System.getProperty("user.home")).getAbsoluteFile(), + File.separator + ".m2" + File.separator + "settings.xml"); + } + +} diff --git a/train-docs/src/main/java/org/springframework/cloud/internal/ConfigurationPropertiesAggregator.java b/train-docs/src/main/java/org/springframework/cloud/internal/ConfigurationPropertiesAggregator.java new file mode 100644 index 0000000..b4f3b8a --- /dev/null +++ b/train-docs/src/main/java/org/springframework/cloud/internal/ConfigurationPropertiesAggregator.java @@ -0,0 +1,62 @@ +/* + * Copyright 2013-2020 the original author or authors. + * + * 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 + * + * https://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. + */ + +package org.springframework.cloud.internal; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.Arrays; +import java.util.Comparator; +import java.util.List; +import java.util.stream.Collectors; + +import org.springframework.util.StringUtils; + +class ConfigurationPropertiesAggregator { + + private static final List wordsToIgnore = Arrays.asList("|===", + "|Name | Default | Description"); + + List mergedConfigurationProperties(Path unpackedDocs) { + try { + return Files.walk(unpackedDocs) + .filter(path -> path.endsWith("_configprops.adoc")).flatMap(path -> { + try { + return Files.readAllLines(path).stream() + .filter(s -> !StringUtils.isEmpty(s) + && !wordsToIgnore.contains(s)) + .map(s -> { + // |foo|bar|baz -> foo|bar|baz -> split -> + // foo,bar,baz + String[] strings = s.substring(1).split("\\|"); + return new ConfigurationProperty( + strings[0].trim(), strings[1].trim(), + strings[2].trim()); + }); + } + catch (IOException e) { + throw new IllegalStateException(e); + } + }).sorted(Comparator.comparing(o -> o.name)) + .collect(Collectors.toList()); + } + catch (IOException e) { + throw new IllegalStateException(e); + } + } + +} diff --git a/train-docs/src/main/java/org/springframework/cloud/internal/ConfigurationProperty.java b/train-docs/src/main/java/org/springframework/cloud/internal/ConfigurationProperty.java new file mode 100644 index 0000000..0ac6171 --- /dev/null +++ b/train-docs/src/main/java/org/springframework/cloud/internal/ConfigurationProperty.java @@ -0,0 +1,66 @@ +/* + * Copyright 2013-2020 the original author or authors. + * + * 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 + * + * https://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. + */ + +package org.springframework.cloud.internal; + +import java.util.Objects; + +class ConfigurationProperty { + + final String name; + + final String defaultValue; + + final String description; + + ConfigurationProperty(String name, String defaultValue, String description) { + this.name = name; + this.defaultValue = defaultValue; + this.description = description; + } + + @Override + public boolean equals(Object o) { + if (this == o) { + return true; + } + if (o == null || getClass() != o.getClass()) { + return false; + } + ConfigurationProperty that = (ConfigurationProperty) o; + return Objects.equals(name, that.name) + && Objects.equals(description, that.description) + && Objects.equals(defaultValue, that.defaultValue); + } + + @Override + public int hashCode() { + return Objects.hash(name, description, defaultValue); + } + + public String getName() { + return name; + } + + public String getDescription() { + return description; + } + + public String getDefaultValue() { + return defaultValue; + } + +} diff --git a/train-docs/src/main/java/org/springframework/cloud/internal/GenerateReleaseTrainDocs.java b/train-docs/src/main/java/org/springframework/cloud/internal/GenerateReleaseTrainDocs.java index 02ae5d3..3052655 100644 --- a/train-docs/src/main/java/org/springframework/cloud/internal/GenerateReleaseTrainDocs.java +++ b/train-docs/src/main/java/org/springframework/cloud/internal/GenerateReleaseTrainDocs.java @@ -1,5 +1,5 @@ /* - * Copyright 2013-2019 the original author or authors. + * Copyright 2013-2020 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -17,149 +17,93 @@ package org.springframework.cloud.internal; import java.io.File; -import java.net.URI; -import java.util.Collections; import java.util.LinkedList; import java.util.List; +import java.util.Objects; import java.util.Properties; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.Future; +import java.util.concurrent.TimeUnit; import java.util.stream.Collectors; import org.apache.maven.model.Model; -import org.apache.maven.repository.internal.MavenRepositorySystemUtils; -import org.apache.maven.settings.Settings; -import org.apache.maven.settings.building.DefaultSettingsBuilderFactory; -import org.apache.maven.settings.building.DefaultSettingsBuildingRequest; -import org.apache.maven.settings.building.SettingsBuilder; -import org.apache.maven.settings.building.SettingsBuildingException; -import org.apache.maven.settings.building.SettingsBuildingRequest; -import org.apache.maven.settings.building.SettingsBuildingResult; -import org.eclipse.aether.DefaultRepositorySystemSession; -import org.eclipse.aether.RepositorySystem; -import org.eclipse.aether.RepositorySystemSession; -import org.eclipse.aether.artifact.Artifact; -import org.eclipse.aether.artifact.DefaultArtifact; -import org.eclipse.aether.connector.basic.BasicRepositoryConnectorFactory; -import org.eclipse.aether.impl.DefaultServiceLocator; -import org.eclipse.aether.repository.LocalRepository; -import org.eclipse.aether.repository.RemoteRepository; -import org.eclipse.aether.repository.RepositoryPolicy; -import org.eclipse.aether.resolution.ArtifactRequest; -import org.eclipse.aether.resolution.ArtifactResult; -import org.eclipse.aether.spi.connector.RepositoryConnectorFactory; -import org.eclipse.aether.spi.connector.transport.TransporterFactory; -import org.eclipse.aether.transport.file.FileTransporterFactory; -import org.eclipse.aether.transport.http.HttpTransporterFactory; -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; -import org.springframework.util.StringUtils; +import static org.springframework.cloud.internal.Logger.info; public class GenerateReleaseTrainDocs { - private static final Logger log = LoggerFactory.getLogger(GenerateReleaseTrainDocs.class); + final ExecutorService service; - List toDocsList(File file) { + public static void main(String... args) { + File bomPath = new File(args[0]); + String repoUrl = args[1]; + File unzippedDocs = new File(args[2]); + File generatedTrainDocs = new File(args[3]); + new GenerateReleaseTrainDocs().generate(bomPath, repoUrl, unzippedDocs, + generatedTrainDocs); + } + + GenerateReleaseTrainDocs() { + this.service = Executors.newFixedThreadPool(4); + } + + void generate(File bomPath, String repoUrl, File unzippedDocs, + File generatedTrainDocs) { + List projects = mavenPropertiesToDocsProjects(bomPath); + info("Found the following projects [" + projects + "]"); + List outputFolders = downloadDocsModules(unzippedDocs, projects, repoUrl); + List configurationProperties = mergeConfigurationProperties( + unzippedDocs); + File file = renderAsciidocTemplates(generatedTrainDocs, projects, + configurationProperties); + info("Rendered docs templates to [" + file + "]"); + new ResourcesCopier().copy(outputFolders, generatedTrainDocs); + } + + List mavenPropertiesToDocsProjects(File file) { Model model = PomReader.readPom(file); Properties properties = model.getProperties(); - return properties.entrySet().stream().filter(e -> e.getKey().toString().endsWith(".version")) - .map(e -> new Project(e.getKey().toString().replace(".version", "-docs"), e.getValue().toString())) + return properties.entrySet().stream() + .filter(e -> e.getKey().toString().endsWith(".version")) + .map(e -> new Project(e.getKey().toString().replace(".version", "-docs"), + e.getValue().toString())) .collect(Collectors.toCollection(LinkedList::new)); } - List downloadDocsModules(List projects, String repoUrl) { - ArtifactFetcher fetcher = new ArtifactFetcher(repoUrl); - return projects.stream().map(fetcher::unpackedDocs).collect(Collectors.toList()); - } - -} - -class ArtifactFetcher { - - private static final Logger log = LoggerFactory.getLogger(ArtifactFetcher.class); - - private final RepositorySystem repositorySystem; - - private final RepositorySystemSession session; - - private final List remoteRepository; - - ArtifactFetcher(String url) { - this.repositorySystem = newRepositorySystem(); - this.session = newSession(this.repositorySystem); - this.remoteRepository = Collections - .singletonList(new RemoteRepository.Builder("remote", "default", url).build()); - } - - File unpackedDocs(Project project) { - String artifactName = project.name; - String version = project.version; + List downloadDocsModules(File outputFolder, List projects, + String repoUrl) { + ArtifactFetcher fetcher = new ArtifactFetcher(outputFolder, repoUrl); try { - Artifact artifact = new DefaultArtifact("org.springframework.cloud", artifactName, "sources", "jar", version); - ArtifactRequest request = new ArtifactRequest(artifact, this.remoteRepository, null); - if (log.isDebugEnabled()) { - log.debug("Resolving artifact [" + artifact + "] using remote repositories " + this.remoteRepository); + List> futures = new LinkedList<>(); + for (Project project : projects) { + futures.add(service.submit(() -> fetcher.unpackedDocs(project))); } - ArtifactResult result = this.repositorySystem.resolveArtifact(this.session, request); - log.info("Resolved artifact [" + artifact + "] to " + result.getArtifact().getFile()); - File unpackedDoc = unpackDoc(artifactName, result.getArtifact().getFile().toURI()); - log.info("Unpacked file to [" + unpackedDoc.getAbsolutePath() + "]"); - return unpackedDoc; + List files = futures.stream().map(future -> { + try { + return future.get(5, TimeUnit.MINUTES); + } + catch (Exception e) { + throw new IllegalStateException(e); + } + }).filter(Objects::nonNull).collect(Collectors.toList()); + info("Unpacked docs modules to the following directories [" + files + "]"); + return files; } - catch (IllegalStateException ise) { - throw ise; - } - catch (Exception e) { - throw new IllegalStateException("Exception occurred while trying to download an artifact with name [" - + artifactName + "] and version [" + version + "] in remote repo [" + this.remoteRepository, e); + finally { + service.shutdown(); } } - private File unpackDoc(String artifactName, URI stubJarUri) { - File unzippedDocs = new File("target/unpacked-docs/" + artifactName); - unzippedDocs.mkdirs(); - log.info("Unpacking stub from JAR [URI: " + stubJarUri + "]"); - ZipCategory.unzipTo(new File(stubJarUri), unzippedDocs); - return unzippedDocs; + List mergeConfigurationProperties(File outputFolderWithDocs) { + ConfigurationPropertiesAggregator aggregator = new ConfigurationPropertiesAggregator(); + return aggregator.mergedConfigurationProperties(outputFolderWithDocs.toPath()); } - private RepositorySystem newRepositorySystem() { - DefaultServiceLocator locator = MavenRepositorySystemUtils.newServiceLocator(); - locator.addService(RepositoryConnectorFactory.class, BasicRepositoryConnectorFactory.class); - locator.addService(TransporterFactory.class, FileTransporterFactory.class); - locator.addService(TransporterFactory.class, HttpTransporterFactory.class); - return locator.getService(RepositorySystem.class); - } - - private RepositorySystemSession newSession(RepositorySystem system) { - DefaultRepositorySystemSession session = MavenRepositorySystemUtils.newSession(); - session.setUpdatePolicy(RepositoryPolicy.UPDATE_POLICY_ALWAYS); - session.setChecksumPolicy(RepositoryPolicy.CHECKSUM_POLICY_WARN); - String localRepository = settings().getLocalRepository(); - localRepository = StringUtils.hasText(localRepository) ? localRepository - : System.getProperty("user.home") + File.separator + ".m2" - + File.separator + "repository"; - LocalRepository localRepo = new LocalRepository(localRepository); - session.setLocalRepositoryManager(system.newLocalRepositoryManager(session, localRepo)); - return session; - } - - private static Settings settings() { - SettingsBuilder builder = new DefaultSettingsBuilderFactory().newInstance(); - SettingsBuildingRequest request = new DefaultSettingsBuildingRequest(); - request.setUserSettingsFile(userSettings()); - SettingsBuildingResult result; - try { - result = builder.build(request); - } - catch (SettingsBuildingException ex) { - throw new IllegalStateException(ex); - } - return result.getEffectiveSettings(); - } - - private static File userSettings() { - return new File(new File(System.getProperty("user.home")).getAbsoluteFile(), - File.separator + ".m2" + File.separator + "settings.xml"); + File renderAsciidocTemplates(File generatedTrainDocs, List projects, + List configurationProperties) { + TemplateGenerator templateGenerator = new TemplateGenerator(generatedTrainDocs); + return templateGenerator.generate(projects, configurationProperties); } } diff --git a/train-docs/src/main/java/org/springframework/cloud/internal/HandlebarsHelper.java b/train-docs/src/main/java/org/springframework/cloud/internal/HandlebarsHelper.java index fca7bcc..7c8b9f8 100644 --- a/train-docs/src/main/java/org/springframework/cloud/internal/HandlebarsHelper.java +++ b/train-docs/src/main/java/org/springframework/cloud/internal/HandlebarsHelper.java @@ -1,5 +1,5 @@ /* - * Copyright 2013-2019 the original author or authors. + * Copyright 2013-2020 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. diff --git a/train-docs/src/main/java/org/springframework/cloud/internal/Logger.java b/train-docs/src/main/java/org/springframework/cloud/internal/Logger.java new file mode 100644 index 0000000..6a8abb3 --- /dev/null +++ b/train-docs/src/main/java/org/springframework/cloud/internal/Logger.java @@ -0,0 +1,29 @@ +/* + * Copyright 2013-2020 the original author or authors. + * + * 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 + * + * https://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. + */ + +package org.springframework.cloud.internal; + +final class Logger { + + private Logger() { + + } + + static void info(String text) { + System.out.println(text); + } + +} diff --git a/train-docs/src/main/java/org/springframework/cloud/internal/PomReader.java b/train-docs/src/main/java/org/springframework/cloud/internal/PomReader.java index 7b5c220..a453d89 100644 --- a/train-docs/src/main/java/org/springframework/cloud/internal/PomReader.java +++ b/train-docs/src/main/java/org/springframework/cloud/internal/PomReader.java @@ -1,5 +1,5 @@ /* - * Copyright 2013-2019 the original author or authors. + * Copyright 2013-2020 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -17,7 +17,6 @@ package org.springframework.cloud.internal; import java.io.File; -import java.io.FileNotFoundException; import java.io.FileReader; import java.io.IOException; import java.io.Reader; @@ -45,7 +44,8 @@ final class PomReader { */ public static Model readPom(File pom) { if (!pom.exists()) { - throw new IllegalStateException("File [" + pom.getAbsolutePath() + "] not found"); + throw new IllegalStateException( + "File [" + pom.getAbsolutePath() + "] not found"); } String fileText = ""; try (Reader reader = new FileReader(pom)) { diff --git a/train-docs/src/main/java/org/springframework/cloud/internal/Project.java b/train-docs/src/main/java/org/springframework/cloud/internal/Project.java index 15d4237..77a3ec1 100644 --- a/train-docs/src/main/java/org/springframework/cloud/internal/Project.java +++ b/train-docs/src/main/java/org/springframework/cloud/internal/Project.java @@ -1,5 +1,5 @@ /* - * Copyright 2013-2019 the original author or authors. + * Copyright 2013-2020 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -38,7 +38,8 @@ class Project { return false; } Project project = (Project) o; - return Objects.equals(name, project.name) && Objects.equals(version, project.version); + return Objects.equals(name, project.name) + && Objects.equals(version, project.version); } @Override @@ -46,4 +47,18 @@ class Project { return Objects.hash(name, version); } + public String getName() { + return name; + } + + public String getVersion() { + return version; + } + + @Override + public String toString() { + return "Project{" + "name='" + this.name + '\'' + ", version='" + this.version + + '\'' + '}'; + } + } diff --git a/train-docs/src/main/java/org/springframework/cloud/internal/ResourcesCopier.java b/train-docs/src/main/java/org/springframework/cloud/internal/ResourcesCopier.java new file mode 100644 index 0000000..e45681b --- /dev/null +++ b/train-docs/src/main/java/org/springframework/cloud/internal/ResourcesCopier.java @@ -0,0 +1,44 @@ +/* + * Copyright 2013-2020 the original author or authors. + * + * 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 + * + * https://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. + */ + +package org.springframework.cloud.internal; + +import java.io.File; +import java.io.IOException; +import java.util.List; + +import org.springframework.util.FileSystemUtils; + +final class ResourcesCopier { + + void copy(List baseDirs, File output) { + File images = new File(output, "images"); + baseDirs.forEach(input -> { + try { + File inputImages = new File(input, "images"); + if (!inputImages.exists()) { + return; + } + Logger.info("Will copy [" + inputImages + "] files to [" + images + "]"); + FileSystemUtils.copyRecursively(inputImages, images); + } + catch (IOException e) { + throw new IllegalStateException(e); + } + }); + } + +} diff --git a/train-docs/src/main/java/org/springframework/cloud/internal/TemplateGenerator.java b/train-docs/src/main/java/org/springframework/cloud/internal/TemplateGenerator.java index 5e3632d..49012ec 100644 --- a/train-docs/src/main/java/org/springframework/cloud/internal/TemplateGenerator.java +++ b/train-docs/src/main/java/org/springframework/cloud/internal/TemplateGenerator.java @@ -1,5 +1,5 @@ /* - * Copyright 2013-2019 the original author or authors. + * Copyright 2013-2020 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -20,46 +20,72 @@ import java.io.File; import java.io.IOException; import java.nio.file.Files; import java.util.HashMap; +import java.util.LinkedList; import java.util.List; import java.util.Map; +import java.util.stream.Collectors; import com.github.jknack.handlebars.Template; import org.springframework.core.io.Resource; import org.springframework.core.io.support.PathMatchingResourcePatternResolver; +import static org.springframework.cloud.internal.Logger.info; + /** * @author Marcin Grzejszczak */ class TemplateGenerator { - static final File OUTPUT_FOLDER = new File("target/train-docs"); + final File outputFolder; - TemplateGenerator() { - OUTPUT_FOLDER.mkdirs(); + TemplateGenerator(File outputFolder) { + this.outputFolder = outputFolder; + this.outputFolder.mkdirs(); } - File generate(List projects) { + File generate(List projects, + List configurationProperties) { PathMatchingResourcePatternResolver resourceLoader = new PathMatchingResourcePatternResolver(); + List projectsWithoutDocs = projects.stream() + .map(p -> new Project(p.name.replace("-docs", ""), p.version)) + .collect(Collectors.toList()); try { - Resource[] resources = resourceLoader.getResources("templates/spring-cloud/*.hbs"); + Resource[] resources = resourceLoader + .getResources("templates/spring-cloud/*.hbs"); for (Resource resource : resources) { File templateFile = resource.getFile(); - File outputFile = new File(OUTPUT_FOLDER, templateFile.getName().replace(".hbs", ".adoc")); + File outputFile = new File(outputFolder, renameTemplate(templateFile)); Template template = template(templateFile.getName().replace(".hbs", "")); Map map = new HashMap<>(); map.put("projects", projects); - map.put("properties", new HashMap<>()); + map.put("projectsWithoutDocs", projectsWithoutDocs); + map.put("springCloudProjects", + projectsWithoutDocs.stream().filter( + project -> project.name.startsWith("spring-cloud-")) + .collect(Collectors.toCollection(LinkedList::new))); + map.put("properties", configurationProperties); String applied = template.apply(map); Files.write(outputFile.toPath(), applied.getBytes()); + info("Successfully rendered [" + outputFile.getAbsolutePath() + "]"); } } catch (IOException e) { throw new IllegalStateException(e); } - return this.OUTPUT_FOLDER; + return outputFolder; } + private String renameTemplate(File templateFile) { + String templateName = templateFile.getName(); + if (templateName.endsWith("-pdf.hbs")) { + return templateName.replace("-pdf.hbs", ".pdfadoc"); + } + else if (templateName.endsWith("-single.hbs")) { + return templateName.replace("-single.hbs", ".htmlsingleadoc"); + } + return templateName.replace(".hbs", ".adoc"); + } private Template template(String template) { return HandlebarsHelper.template(template); diff --git a/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-attributes.hbs b/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-attributes.hbs index d24e25f..c9054d3 100644 --- a/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-attributes.hbs +++ b/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-attributes.hbs @@ -1,2 +1,2 @@ -{{#each projects}} :{{name}}-version: {{version}} +{{#each projectsWithoutDocs}}:{{name}}-version: {{version}} {{/each}} diff --git a/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-links.hbs b/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-links.hbs index ca333b6..4be4b68 100644 --- a/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-links.hbs +++ b/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-links.hbs @@ -1,2 +1,2 @@ -{{#each projects}} https://docs.spring.io/{{name}}/docs/{{version}}/reference/html/[{{name}}] :: {{name}} Reference Documentation, version {{version}} +{{#each springCloudProjects}} https://docs.spring.io/{{name}}/docs/{{version}}/reference/html/[{{name}}] :: {{name}} Reference Documentation, version {{version}} {{/each}} diff --git a/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-versions.hbs b/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-versions.hbs index 6ae15ac..012bf74 100644 --- a/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-versions.hbs +++ b/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-versions.hbs @@ -1,2 +1,2 @@ -{{#each projects}} |{{name}}|{{version}} +{{#each projectsWithoutDocs}} |{{name}}|{{version}} {{/each}} \ No newline at end of file diff --git a/train-docs/src/main/resources/templates/spring-cloud/configprops.hbs b/train-docs/src/main/resources/templates/spring-cloud/configprops.hbs index 3462d60..267b519 100644 --- a/train-docs/src/main/resources/templates/spring-cloud/configprops.hbs +++ b/train-docs/src/main/resources/templates/spring-cloud/configprops.hbs @@ -1,7 +1,7 @@ |=== |Name | Default | Description -{{#each properties}} |{{name}} | {{default}} | {{description}} +{{#each properties}} |{{name}} | {{defaultValue}} | {{description}} {{/each}} |=== \ No newline at end of file diff --git a/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-pdf.hbs b/train-docs/src/main/resources/templates/spring-cloud/spring-cloud-pdf.hbs similarity index 86% rename from train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-pdf.hbs rename to train-docs/src/main/resources/templates/spring-cloud/spring-cloud-pdf.hbs index 7103342..2fa2d8b 100644 --- a/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-pdf.hbs +++ b/train-docs/src/main/resources/templates/spring-cloud/spring-cloud-pdf.hbs @@ -4,7 +4,6 @@ include::_attributes.adoc[] include::_spring-cloud-attributes.adoc[] :basedir: {project-root} -:stream_basedir: {basedir} :project-full-name: Spring Cloud :project-name: spring-cloud @@ -45,11 +44,13 @@ and extensibility mechanism to cover others. include::_spring-cloud-versions.adoc[] |=== -{{#each projects}} -:project-root: {basedir}/{{name}}-docs -:project-version: { {{name}}-version } -include::{basedir}/{{name}}-docs/{{name}}.adoc[leveloffset=+1] -{{/each}} +{{=<% %>=}} +<%#each springCloudProjects%> +:project-root: {unpackedDocsBaseDir}/<%name%>-docs +:project-version: {<%name%>-version} +include::{unpackedDocsBaseDir}/<%name%>-docs/<%name%>.adoc[leveloffset=+1] +<%/each%> +<%={{ }}=%> = Appendix: Compendium of Configuration Properties diff --git a/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-single.hbs b/train-docs/src/main/resources/templates/spring-cloud/spring-cloud-single.hbs similarity index 86% rename from train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-single.hbs rename to train-docs/src/main/resources/templates/spring-cloud/spring-cloud-single.hbs index 7103342..2fa2d8b 100644 --- a/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud-single.hbs +++ b/train-docs/src/main/resources/templates/spring-cloud/spring-cloud-single.hbs @@ -4,7 +4,6 @@ include::_attributes.adoc[] include::_spring-cloud-attributes.adoc[] :basedir: {project-root} -:stream_basedir: {basedir} :project-full-name: Spring Cloud :project-name: spring-cloud @@ -45,11 +44,13 @@ and extensibility mechanism to cover others. include::_spring-cloud-versions.adoc[] |=== -{{#each projects}} -:project-root: {basedir}/{{name}}-docs -:project-version: { {{name}}-version } -include::{basedir}/{{name}}-docs/{{name}}.adoc[leveloffset=+1] -{{/each}} +{{=<% %>=}} +<%#each springCloudProjects%> +:project-root: {unpackedDocsBaseDir}/<%name%>-docs +:project-version: {<%name%>-version} +include::{unpackedDocsBaseDir}/<%name%>-docs/<%name%>.adoc[leveloffset=+1] +<%/each%> +<%={{ }}=%> = Appendix: Compendium of Configuration Properties diff --git a/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud.hbs b/train-docs/src/main/resources/templates/spring-cloud/spring-cloud.hbs similarity index 93% rename from train-docs/src/main/resources/templates/spring-cloud/_spring-cloud.hbs rename to train-docs/src/main/resources/templates/spring-cloud/spring-cloud.hbs index 252d594..ead7c38 100644 --- a/train-docs/src/main/resources/templates/spring-cloud/_spring-cloud.hbs +++ b/train-docs/src/main/resources/templates/spring-cloud/spring-cloud.hbs @@ -4,7 +4,6 @@ include::_attributes.adoc[] include::_spring-cloud-attributes.adoc[] :basedir: {project-root} -:stream_basedir: {basedir} Spring Cloud provides tools for developers to quickly build some of the common patterns in distributed systems (e.g. configuration @@ -42,5 +41,4 @@ include::_spring-cloud-links.adoc[] = Appendix: Compendium of Configuration Properties -// need to combine all configprops from all files into a single table link:configprops.html[Spring Cloud configuration properties] diff --git a/train-docs/src/test/java/org/springframework/cloud/internal/GenerateReleaseTrainDocsTests.java b/train-docs/src/test/java/org/springframework/cloud/internal/GenerateReleaseTrainDocsTests.java new file mode 100644 index 0000000..ae1f3bb --- /dev/null +++ b/train-docs/src/test/java/org/springframework/cloud/internal/GenerateReleaseTrainDocsTests.java @@ -0,0 +1,112 @@ +/* + * Copyright 2013-2020 the original author or authors. + * + * 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 + * + * https://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. + */ + +package org.springframework.cloud.internal; + +import java.io.File; +import java.io.IOException; +import java.net.URISyntaxException; +import java.nio.file.Files; +import java.util.Arrays; +import java.util.List; + +import org.assertj.core.api.BDDAssertions; +import org.junit.jupiter.api.Test; + +import org.springframework.util.FileSystemUtils; + +public class GenerateReleaseTrainDocsTests { + + @Test + void should_return_a_list_of_docs_modules_to_download() throws URISyntaxException { + File testPom = new File( + GenerateReleaseTrainDocsTests.class.getResource("/test/pom.xml").toURI()); + + List projects = new GenerateReleaseTrainDocs() + .mavenPropertiesToDocsProjects(testPom); + + BDDAssertions.then(projects).extracting("name").containsOnly( + "spring-cloud-bus-docs", "spring-cloud-build-docs", + "spring-cloud-cloudfoundry-docs", "spring-cloud-commons-docs", + "spring-cloud-circuitbreaker-docs", "spring-cloud-config-docs", + "spring-cloud-consul-docs", "spring-cloud-contract-docs", + "spring-cloud-function-docs", "spring-cloud-gateway-docs", + "spring-cloud-kubernetes-docs", "spring-cloud-netflix-docs", + "spring-cloud-openfeign-docs", "spring-cloud-security-docs", + "spring-cloud-sleuth-docs", "spring-cloud-stream-docs", + "spring-cloud-task-docs", "spring-cloud-vault-docs", + "spring-cloud-zookeeper-docs", "spring-cloud-cli-docs"); + BDDAssertions.then(projects) + .contains(new Project("spring-cloud-bus-docs", "1.2.3-SNAPSHOT")); + } + + @Test + void should_unpack_starters_docs() throws URISyntaxException { + File testPom = new File(GenerateReleaseTrainDocsTests.class + .getResource("/test/sleuth-only.xml").toURI()); + File unzippedDocs = new File("target/unpacked-docs/"); + List projects = new GenerateReleaseTrainDocs() + .mavenPropertiesToDocsProjects(testPom); + + new GenerateReleaseTrainDocs().downloadDocsModules(unzippedDocs, projects, + "https://repo.spring.io/libs-snapshot-local/"); + + BDDAssertions.then(unzippedDocs).isNotEmptyDirectory(); + } + + @Test + void should_generate_adocs_from_templates() { + File file = new File("target/train-docs"); + FileSystemUtils.deleteRecursively(file); + List projects = Arrays.asList(new Project("spring-cloud-foo", "1.0.0"), + new Project("spring-cloud-bar", "2.0.0"), + new Project("spring-boot", "3.0.0"), + new Project("spring-cloud", "4.0.0")); + List configurationProperties = Arrays.asList( + new ConfigurationProperty("first", "firstDefault", "firstDescription"), + new ConfigurationProperty("second", "secondDefault", + "secondDescription")); + + File outputFolder = new TemplateGenerator(file).generate(projects, + configurationProperties); + + BDDAssertions.then(outputFolder).isNotEmptyDirectory(); + } + + @Test + void should_generate_adocs_from_spring_cloud_sleuth_docs() + throws URISyntaxException, IOException { + File generatedAdocs = new File("target/train-docs"); + FileSystemUtils.deleteRecursively(generatedAdocs); + File testPom = new File(GenerateReleaseTrainDocsTests.class + .getResource("/test/sleuth-only.xml").toURI()); + File unzippedDocs = new File("target/unpacked-docs/"); + + GenerateReleaseTrainDocs.main(testPom.getAbsolutePath(), + "https://repo.spring.io/libs-snapshot-local/", + unzippedDocs.getAbsolutePath(), generatedAdocs.getAbsolutePath()); + + BDDAssertions.then(generatedAdocs).isNotEmptyDirectory(); + BDDAssertions.then(configProps(generatedAdocs)).contains( + "|spring.sleuth.async.configurer.enabled | true | Enable default AsyncConfigurer."); + } + + private String configProps(File file) throws IOException { + return new String( + Files.readAllBytes(new File(file, "configprops.adoc").toPath())); + } + +} diff --git a/train-docs/src/test/java/org/springframework/cloud/internal/SomethingTest.java b/train-docs/src/test/java/org/springframework/cloud/internal/SomethingTest.java deleted file mode 100644 index ddde79c..0000000 --- a/train-docs/src/test/java/org/springframework/cloud/internal/SomethingTest.java +++ /dev/null @@ -1,76 +0,0 @@ -/* - * Copyright 2013-2019 the original author or authors. - * - * 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 - * - * https://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. - */ - -package org.springframework.cloud.internal; - -import java.io.File; -import java.net.URISyntaxException; -import java.util.Arrays; -import java.util.List; - -import org.assertj.core.api.BDDAssertions; -import org.junit.jupiter.api.Test; - -import org.springframework.util.FileSystemUtils; - -public class SomethingTest { - - @Test - void should_return_a_list_of_docs_modules_to_download() throws URISyntaxException { - File testPom = new File(SomethingTest.class.getResource("/test/pom.xml").toURI()); - - List projects = new GenerateReleaseTrainDocs().toDocsList(testPom); - - BDDAssertions.then(projects) - .extracting("name") - .containsOnly("spring-cloud-bus-docs", "spring-cloud-build-docs", - "spring-cloud-cloudfoundry-docs", "spring-cloud-commons-docs", "spring-cloud-circuitbreaker-docs", - "spring-cloud-config-docs", "spring-cloud-consul-docs", "spring-cloud-contract-docs", - "spring-cloud-function-docs", "spring-cloud-gateway-docs", "spring-cloud-kubernetes-docs", - "spring-cloud-netflix-docs", "spring-cloud-openfeign-docs", "spring-cloud-security-docs", - "spring-cloud-sleuth-docs", "spring-cloud-stream-docs", "spring-cloud-task-docs", - "spring-cloud-vault-docs", "spring-cloud-zookeeper-docs", "spring-cloud-cli-docs"); - BDDAssertions.then(projects).contains(new Project("spring-cloud-bus-docs", "1.2.3-SNAPSHOT")); - } - - @Test - void should_unpack_starters_docs() throws URISyntaxException { - File testPom = new File(SomethingTest.class.getResource("/test/sleuth-only.xml").toURI()); - String remoteRepo = "https://repo.spring.io/libs-snapshot-local/"; - List projects = new GenerateReleaseTrainDocs().toDocsList(testPom); - - List files = new GenerateReleaseTrainDocs().downloadDocsModules(projects, "https://repo.spring.io/libs-snapshot-local/"); - - BDDAssertions.then(files) - .isNotEmpty(); - } - - @Test - void should_generate_the_single_pdf_multi_adoc_pages() { - - } - - @Test - void should_generate_adocs_from_templates() { - FileSystemUtils.deleteRecursively(TemplateGenerator.OUTPUT_FOLDER); - List projects = Arrays.asList(new Project("spring-cloud-foo", "1.0.0"), new Project("spring-cloud-bar", "2.0.0")); - - File outputFolder = new TemplateGenerator().generate(projects); - - BDDAssertions.then(outputFolder).isNotEmptyDirectory(); - } - -} diff --git a/train-docs/src/test/java/org/springframework/cloud/internal/TestThatGeneratesTheFinalReleaseTrainDocumentationTests.java b/train-docs/src/test/java/org/springframework/cloud/internal/TestThatGeneratesTheFinalReleaseTrainDocumentationTests.java new file mode 100644 index 0000000..9dd047c --- /dev/null +++ b/train-docs/src/test/java/org/springframework/cloud/internal/TestThatGeneratesTheFinalReleaseTrainDocumentationTests.java @@ -0,0 +1,48 @@ +/* + * Copyright 2013-2020 the original author or authors. + * + * 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 + * + * https://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. + */ + +package org.springframework.cloud.internal; + +import java.io.File; + +import org.assertj.core.api.BDDAssertions; +import org.junit.jupiter.api.Assumptions; +import org.junit.jupiter.api.Test; + +import org.springframework.util.StringUtils; + +public class TestThatGeneratesTheFinalReleaseTrainDocumentationTests { + + /** + * FOR SOME REASON I CAN'T RUN MAIN CLASS FROM MAVEN AS A WORKAOUND WE WILL RUN THIS + * TEST TO GENERATE THE DOCS + */ + @Test + void should_generate_adocs_with_values_from_system_property() { + // System property needs to be passed + Assumptions.assumeTrue(StringUtils.hasText(System.getProperty("bomPath"))); + + String bomPath = System.getProperty("bomPath"); + String repoUrl = System.getProperty("repoUrl"); + String unzippedDocs = System.getProperty("unzippedDocs"); + String generatedTrainDocs = System.getProperty("generatedTrainDocs"); + + GenerateReleaseTrainDocs.main(bomPath, repoUrl, unzippedDocs, generatedTrainDocs); + + BDDAssertions.then(new File(generatedTrainDocs)).isNotEmptyDirectory(); + } + +} diff --git a/train-docs/src/test/resources/adocs/legal.adoc b/train-docs/src/test/resources/adocs/legal.adoc index f287221..048c5ad 100644 --- a/train-docs/src/test/resources/adocs/legal.adoc +++ b/train-docs/src/test/resources/adocs/legal.adoc @@ -3,7 +3,7 @@ {spring-cloud-version} -Copyright © 2012-2019 +Copyright © 2012-2020 Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further diff --git a/train-docs/src/test/resources/logback.xml b/train-docs/src/test/resources/logback.xml index 9da197f..96d75b7 100644 --- a/train-docs/src/test/resources/logback.xml +++ b/train-docs/src/test/resources/logback.xml @@ -1,5 +1,5 @@