This is an automated email from the ASF dual-hosted git repository. epugh pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/solr.git
commit d5ab54e70eafabbcd04448993305a6ceea837a0a Author: Houston Putman <[email protected]> AuthorDate: Thu Feb 10 13:52:19 2022 -0500 SOLR-15556: Add real branches for official ref-guide * Make the site generation quicker by allowing parallel generation of javadocs. * Fix inputs for the antora yaml generation, does not cache when values need to change. --- solr/solr-ref-guide/README.adoc | 10 ++++++-- solr/solr-ref-guide/build.gradle | 52 +++++++++++++++++++++++++++------------- 2 files changed, 44 insertions(+), 18 deletions(-) diff --git a/solr/solr-ref-guide/README.adoc b/solr/solr-ref-guide/README.adoc index ecb833d..443180a 100644 --- a/solr/solr-ref-guide/README.adoc +++ b/solr/solr-ref-guide/README.adoc @@ -20,7 +20,7 @@ This is the source for the Solr Reference Guide. Raw content is stored in Asciidoc (`.adoc`) formatted files in the `modules/` directory. -To build the Ref Guide, simply run `./gradlew buildLocalSite`. +To build the Ref Guide, run `./gradlew buildLocalSite`. This will build the HTML files and validate that page references and internal links work properly. You can find the home page of the generated site under `build/site/index.html` @@ -28,4 +28,10 @@ See the `../../dev-docs/ref-guide` directory for information about editing and p To ignore the Ref Guide steps when running gradle `assemble` or `check`, use either `-Prefguide.include=false` or `SOLR_REF_GUIDE_INCLUDE=false`. -If you want to test any changes for the Site UI files in `ui-src`, then use either `-Prefguide.buildLocalUI=false` or `SOLR_REF_GUIDE_BUILD_LOCAL_UI=false` when building the local or official site. +If you want to test any changes for the Site UI files in `ui-src`, then use either `-Prefguide.buildLocalUI=true` or `SOLR_REF_GUIDE_BUILD_LOCAL_UI=true` when building the local or official site. + +In order to build the official ref guide, run `./gradlew buildOfficialSite`. It will also be built under `build/site/`. +Note, this will not include any local changes to the ref guide, just what is published to git. +By default it will not include prerelase versions (the `main` and `branch_*x` branches), just the release versions (i.e. `branch_x_y`). +You can include all prerelease versions by including `-Prefguide.official.includePrereleaseVersions=true` or `SOLR_REF_GUIDE_OFFICIAL_INCLUDE_PRERELEASE=true` when building the official ref guide. +This is the option that is used when generating the nightlies refGuide release. diff --git a/solr/solr-ref-guide/build.gradle b/solr/solr-ref-guide/build.gradle index 013f0ab..d349673 100644 --- a/solr/solr-ref-guide/build.gradle +++ b/solr/solr-ref-guide/build.gradle @@ -23,6 +23,8 @@ plugins { description = 'Solr Reference Guide' +def officialSiteIncludePrerelease = propertyOrEnvOrDefault("refguide.official.includePrereleaseVersions", "SOLR_REF_GUIDE_OFFICIAL_INCLUDE_PRERELEASE", "false").toBoolean() + def buildLocalUI = propertyOrEnvOrDefault("refguide.buildLocalUI", "SOLR_REF_GUIDE_BUILD_LOCAL_UI", "false").toBoolean() // Attach building the ref guide to standard convention tasks. This @@ -36,11 +38,12 @@ configurations { refGuide officialPlaybook localPlaybook + localJavadocs } dependencies { - localPlaybook project(path: ":solr:documentation", configuration: 'javadocs') - localPlaybook project(path: ":solr:documentation", configuration: 'site') + localJavadocs project(path: ":solr:documentation", configuration: 'javadocs') + localJavadocs project(path: ":solr:documentation", configuration: 'site') } ext { @@ -71,14 +74,19 @@ task buildLocalAntoraYaml { inputs.file(templateYaml) outputs.file(project.ext.localAntoraYaml) + def splitVersion = version.toString().split("\\p{Punct}") + def props = [ + solr_version : "${splitVersion[0]}.${splitVersion[1]}.${splitVersion[2]}", + solr_version_major : splitVersion[0], + solr_version_minor : splitVersion[1], + solr_version_patch : splitVersion[2], + ] + props.putAll([ + solr_javadocs_link : "https://solr.apache.org/docs/${props.solr_version.replaceAll("\\.", "_")}", + lucene_javadocs_link : project(':solr:documentation').luceneDocUrl, + ]) + doLast { - def splitVersion = version.toString().split("\\p{Punct}") - def props = [ - solr_version : "${splitVersion[0]}.${splitVersion[1]}.${splitVersion[2]}", - solr_version_major : splitVersion[0], - solr_version_minor : splitVersion[1], - solr_version_patch : splitVersion[2], - ] // Set these dependency versions as lazy gstrings so that they're resolved after evaluation. // These variable names must use underscores, not dashes or periods props.putAll([ @@ -92,10 +100,6 @@ task buildLocalAntoraYaml { ["dep_version_lucene", "org.apache.lucene", "lucene-core"], ].collectEntries { propKey, depGroup, depId -> [propKey, "${-> project.getVersion(depGroup, depId)}"] }) - props.putAll([ - solr_javadocs_link : "https://solr.apache.org/docs/${props.solr_version.replaceAll("\\.", "_")}", - lucene_javadocs_link : project(':solr:documentation').luceneDocUrl, - ]) copy { from(templateYaml) { @@ -108,6 +112,7 @@ task buildLocalAntoraYaml { expand(props) } } + inputs.properties(props) } task buildLocalAntoraPlaybookYaml(type: Copy) { @@ -146,11 +151,18 @@ task buildOfficialAntoraPlaybookYaml(type: Copy) { } into project.ext.playbooksDir + def branches = ["branch_*"] + if (officialSiteIncludePrerelease) { + branches.add("main") + } else { + branches.add("\"!branch_*x\"") + } + def props = [ 'site_url' : "https://solr.apache.org/guide";, 'redirect_facility' : "httpd", 'source_url' : "https://github.com/apache/solr.git";, - 'source_branches' : ["jira/solr-15556-antora"], + 'source_branches' : branches, 'start_path' : 'solr/solr-ref-guide', 'supplemental_files' : "${project.ext.nodeProjectDir}/node_modules/@antora/lunr-extension/supplemental_ui", 'site_dir' : "./" + file(project.ext.playbooksDir).relativePath(file(project.ext.siteDir)), @@ -356,7 +368,7 @@ task setupLocalSiteStagingDir(type: Sync) { into project.ext.siteStagingDir } -task buildLocalSite(type: NpxTask) { +task buildLocalAntoraSite(type: NpxTask) { group = 'Site - Local' description "Creates a local build of the ref-guide." @@ -392,10 +404,18 @@ task buildLocalSite(type: NpxTask) { inputs.files(fileTree(project.ext.siteStagingDir)) inputs.property("Antora version", project.ext.antoraVersion) outputs.dir(project.ext.siteDir) +} + +task buildLocalSite { + group = 'Site - Local' + description "Creates a local build of the ref-guide, with local javadocs to link to." + + dependsOn tasks.buildLocalAntoraSite + dependsOn configurations.localJavadocs doLast { project.logger.lifecycle("The generated local ref-guide can be found at:") - project.logger.lifecycle("\t${project.ext.siteDir}") + project.logger.lifecycle("\t${project.ext.siteDir}/index.html") } }
