From 2cc7f8ec397319951bb73369be3cdb3ef76f700b Mon Sep 17 00:00:00 2001 From: Janne Valkealahti Date: Fri, 28 Apr 2023 13:36:09 +0100 Subject: [PATCH] Migrate docs to spring-asciidoctor-backends - Use io.spring.asciidoctor.backends:spring-asciidoctor-backends:0.0.5 - As this relates to anon repo access, use ge conventions from public repos and fix some other used repos. - Fixes #722 --- buildSrc/build.gradle | 3 +- .../shell/gradle/DocsPlugin.java | 217 ++++++------------ gradle.properties | 2 +- 3 files changed, 79 insertions(+), 143 deletions(-) diff --git a/buildSrc/build.gradle b/buildSrc/build.gradle index d52d3812..a799864a 100644 --- a/buildSrc/build.gradle +++ b/buildSrc/build.gradle @@ -9,7 +9,8 @@ repositories { gradlePluginPortal() mavenCentral() maven { url 'https://repo.spring.io/plugins-release/' } - maven { url "https://repo.spring.io/snapshot" } + maven { url 'https://repo.spring.io/milestone' } + maven { url 'https://repo.spring.io/snapshot' } } ext { diff --git a/buildSrc/src/main/java/org/springframework/shell/gradle/DocsPlugin.java b/buildSrc/src/main/java/org/springframework/shell/gradle/DocsPlugin.java index b12432c3..8ce5d3b7 100644 --- a/buildSrc/src/main/java/org/springframework/shell/gradle/DocsPlugin.java +++ b/buildSrc/src/main/java/org/springframework/shell/gradle/DocsPlugin.java @@ -1,5 +1,5 @@ /* - * Copyright 2022 the original author or authors. + * Copyright 2022-2023 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. @@ -16,18 +16,14 @@ package org.springframework.shell.gradle; import java.io.File; -import java.net.URI; import java.time.LocalDate; -import java.util.ArrayList; import java.util.Collections; import java.util.HashMap; -import java.util.List; import java.util.Map; -import java.util.concurrent.Callable; -import java.util.function.Consumer; import org.asciidoctor.gradle.base.AsciidoctorAttributeProvider; import org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask; +import org.asciidoctor.gradle.jvm.AsciidoctorJExtension; import org.asciidoctor.gradle.jvm.AsciidoctorJPlugin; import org.asciidoctor.gradle.jvm.AsciidoctorTask; import org.gradle.api.Action; @@ -38,17 +34,18 @@ import org.gradle.api.plugins.JavaLibraryPlugin; import org.gradle.api.plugins.JavaPlugin; import org.gradle.api.plugins.PluginManager; import org.gradle.api.publish.tasks.GenerateModuleMetadata; -import org.gradle.api.artifacts.Configuration; -import org.gradle.api.artifacts.dsl.RepositoryHandler; -import org.gradle.api.file.CopySpec; -import org.gradle.api.file.FileTree; +import org.gradle.api.tasks.PathSensitivity; import org.gradle.api.tasks.Sync; +import org.springframework.util.StringUtils; /** * @author Janne Valkealahti */ class DocsPlugin implements Plugin { + private static final String ASCIIDOCTORJ_VERSION = "2.4.3"; + private static final String EXTENSIONS_CONFIGURATION_NAME = "asciidoctorExtensions"; + @Override public void apply(Project project) { PluginManager pluginManager = project.getPluginManager(); @@ -63,133 +60,83 @@ class DocsPlugin implements Plugin { task.enforcedPlatform(":spring-shell-management"); }); - configureAdocPlugins(project, dependencyVersions); - + project.getPlugins().withType(AsciidoctorJPlugin.class, (asciidoctorPlugin) -> { + // makeAllWarningsFatal(project); + upgradeAsciidoctorJVersion(project); + createAsciidoctorExtensionsConfiguration(project); + project.getTasks() + .withType(AbstractAsciidoctorTask.class, + (asciidoctorTask) -> configureAsciidoctorTask(project, asciidoctorTask, dependencyVersions)); + }); project.getTasks().withType(GenerateModuleMetadata.class, metadata -> { metadata.setEnabled(false); }); } - private void configureAdocPlugins(Project project, ExtractVersionConstraints dependencyVersions) { - project.getPlugins().withType(AsciidoctorJPlugin.class, (asciidoctorPlugin) -> { - createDefaultAsciidoctorRepository(project); - makeAllWarningsFatal(project); - Sync unzipResources = createUnzipDocumentationResourcesTask(project); - Sync snippetsResources = createSnippetsResourcesTask(project); - project.getTasks().withType(AbstractAsciidoctorTask.class, (asciidoctorTask) -> { - asciidoctorTask.dependsOn(dependencyVersions); - asciidoctorTask.dependsOn(unzipResources); - asciidoctorTask.dependsOn(snippetsResources); - // configureExtensions(project, asciidoctorTask); - configureCommonAttributes(project, asciidoctorTask); - configureOptions(asciidoctorTask); - asciidoctorTask.sourceDir("src/main/asciidoc"); - asciidoctorTask.baseDirFollowsSourceDir(); - asciidoctorTask.useIntermediateWorkDir(); - asciidoctorTask.resources(new Action() { - @Override - public void execute(CopySpec resourcesSpec) { - resourcesSpec.from(unzipResources); - // resourcesSpec.from(snippetsResources); - resourcesSpec.from(snippetsResources, copySpec -> { - copySpec.include("docs/*"); - }); - resourcesSpec.from(asciidoctorTask.getSourceDir(), new Action() { - @Override - public void execute(CopySpec resourcesSrcDirSpec) { - // https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/523 - // For now copy the entire sourceDir over so that include files are - // available in the intermediateWorkDir - resourcesSrcDirSpec.include("images/*"); - resourcesSrcDirSpec.include("code/*"); - } - }); - } - }); - if (asciidoctorTask instanceof AsciidoctorTask) { - configureHtmlOnlyAttributes(project, asciidoctorTask, dependencyVersions); - } - }); + private void upgradeAsciidoctorJVersion(Project project) { + project.getExtensions().getByType(AsciidoctorJExtension.class).setVersion(ASCIIDOCTORJ_VERSION); + } + + private void createAsciidoctorExtensionsConfiguration(Project project) { + project.getConfigurations().create(EXTENSIONS_CONFIGURATION_NAME, (configuration) -> { + configuration.getDependencies() + .add(project.getDependencies() + .create("io.spring.asciidoctor.backends:spring-asciidoctor-backends:0.0.5")); }); } - private void createDefaultAsciidoctorRepository(Project project) { - project.getGradle().afterProject(new Action() { - @Override - public void execute(Project project) { - RepositoryHandler repositories = project.getRepositories(); - if (repositories.isEmpty()) { - repositories.mavenCentral(); - repositories.maven(repo -> { - repo.setUrl(URI.create("https://repo.spring.io/release")); - }); - } - } - }); - } - - private void makeAllWarningsFatal(Project project) { - // project.getExtensions().getByType(AsciidoctorJExtension.class).fatalWarnings(".*"); - } - - // private void configureExtensions(Project project, AbstractAsciidoctorTask asciidoctorTask) { - // Configuration extensionsConfiguration = project.getConfigurations().maybeCreate("asciidoctorExtensions"); - // extensionsConfiguration.defaultDependencies(new Action() { - // @Override - // public void execute(DependencySet dependencies) { - // dependencies.add(project.getDependencies().create("io.spring.asciidoctor:spring-asciidoctor-extensions-block-switch:0.4.2.RELEASE")); - // } - // }); - // asciidoctorTask.configurations(extensionsConfiguration); - // } - - private Sync createSnippetsResourcesTask(Project project) { - Sync sync = project.getTasks().create("snippetResources", Sync.class, s -> { - s.from(new File(project.getRootProject().getRootDir(), "spring-shell-docs/src/test/java/org/springframework/shell"), spec -> { - spec.include("docs/*"); - }); - File destination = new File(project.getBuildDir(), "docs/snippets"); - s.into(destination); - }); - return sync; - } - - private Sync createUnzipDocumentationResourcesTask(Project project) { - Configuration documentationResources = project.getConfigurations().maybeCreate("documentationResources"); - documentationResources.getDependencies() - .add(project.getDependencies().create("io.spring.docresources:spring-doc-resources:0.2.5")); - Sync unzipResources = project.getTasks().create("unzipDocumentationResources", - Sync.class, new Action() { - @Override - public void execute(Sync sync) { - sync.dependsOn(documentationResources); - sync.from(new Callable>() { - @Override - public List call() throws Exception { - List result = new ArrayList<>(); - documentationResources.getAsFileTree().forEach(new Consumer() { - @Override - public void accept(File file) { - result.add(project.zipTree(file)); - } - }); - return result; - } - }); - File destination = new File(project.getBuildDir(), "docs/resources"); - sync.into(project.relativePath(destination)); - } - }); - return unzipResources; + private void configureAsciidoctorTask(Project project, AbstractAsciidoctorTask asciidoctorTask, ExtractVersionConstraints dependencyVersions) { + asciidoctorTask.configurations(EXTENSIONS_CONFIGURATION_NAME); + configureCommonAttributes(project, asciidoctorTask, dependencyVersions); + configureOptions(asciidoctorTask); + asciidoctorTask.baseDirFollowsSourceDir(); + createSyncDocumentationSourceTask(project, asciidoctorTask, dependencyVersions); + if (asciidoctorTask instanceof AsciidoctorTask task) { + task.outputOptions((outputOptions) -> outputOptions.backends("spring-html")); + } } private void configureOptions(AbstractAsciidoctorTask asciidoctorTask) { asciidoctorTask.options(Collections.singletonMap("doctype", "book")); } - private void configureHtmlOnlyAttributes(Project project, AbstractAsciidoctorTask asciidoctorTask, - ExtractVersionConstraints dependencyVersions) { + private Sync createSyncDocumentationSourceTask(Project project, AbstractAsciidoctorTask asciidoctorTask, ExtractVersionConstraints dependencyVersions) { + Sync syncDocumentationSource = project.getTasks() + .create("syncDocumentationSourceFor" + StringUtils.capitalize(asciidoctorTask.getName()), Sync.class); + syncDocumentationSource.preserve(filter -> { + filter.include("**/*"); + }); + File syncedSource = new File(project.getBuildDir(), "docs/src/" + asciidoctorTask.getName()); + syncDocumentationSource.setDestinationDir(syncedSource); + syncDocumentationSource.from("src/main/"); + asciidoctorTask.dependsOn(syncDocumentationSource); + asciidoctorTask.dependsOn(dependencyVersions); + Sync snippetsResources = createSnippetsResourcesTask(project); + asciidoctorTask.dependsOn(snippetsResources); + asciidoctorTask.getInputs() + .dir(syncedSource) + .withPathSensitivity(PathSensitivity.RELATIVE) + .withPropertyName("synced source"); + asciidoctorTask.setSourceDir(project.relativePath(new File(syncedSource, "asciidoc/"))); + return syncDocumentationSource; + } + private Sync createSnippetsResourcesTask(Project project) { + Sync sync = project.getTasks().create("snippetResources", Sync.class, s -> { + s.from(new File(project.getRootProject().getRootDir(), "spring-shell-docs/src/test/java/org/springframework/shell"), spec -> { + spec.include("docs/*"); + }); + s.preserve(filter -> { + filter.include("**/*"); + }); + File destination = new File(project.getBuildDir(), "docs/src/asciidoctor/asciidoc"); + s.into(destination); + }); + return sync; + } + + private void configureCommonAttributes(Project project, AbstractAsciidoctorTask asciidoctorTask, + ExtractVersionConstraints dependencyVersions) { asciidoctorTask.doFirst(new Action() { @Override @@ -209,13 +156,15 @@ class DocsPlugin implements Plugin { Map attributes = new HashMap<>(); attributes.put("toc", "left"); - attributes.put("source-highlighter", "highlight.js"); - attributes.put("highlightjsdir", "js/highlight"); - attributes.put("highlightjs-theme", "github"); - attributes.put("linkcss", true); attributes.put("icons", "font"); - attributes.put("stylesheet", "css/spring.css"); + attributes.put("idprefix", ""); + attributes.put("idseparator", "-"); + attributes.put("docinfo", "shared"); + attributes.put("sectanchors", ""); + attributes.put("sectnums", ""); + attributes.put("today-year", LocalDate.now().getYear()); attributes.put("snippets", "docs"); + asciidoctorTask.getAttributeProviders().add(new AsciidoctorAttributeProvider() { @Override public Map getAttributes() { @@ -229,18 +178,4 @@ class DocsPlugin implements Plugin { }); asciidoctorTask.attributes(attributes); } - - private void configureCommonAttributes(Project project, AbstractAsciidoctorTask asciidoctorTask) { - Map attributes = new HashMap<>(); - // attributes.put("attribute-missing", "warn"); - attributes.put("icons", "font"); - attributes.put("idprefix", ""); - attributes.put("idseparator", "-"); - attributes.put("docinfo", "shared"); - attributes.put("sectanchors", ""); - attributes.put("sectnums", ""); - attributes.put("today-year", LocalDate.now().getYear()); - asciidoctorTask.attributes(attributes); - } - } diff --git a/gradle.properties b/gradle.properties index 7c79f4d3..1c9523cd 100644 --- a/gradle.properties +++ b/gradle.properties @@ -6,6 +6,6 @@ jlineVersion=3.21.0 st4Version=4.3.1 jimfsVersion=1.2 gradleEnterpriseVersion=3.10.3 -springGeConventionsVersion=0.0.11 +springGeConventionsVersion=0.0.13 findbugsVersion=3.0.2 org.gradle.caching=true