Skip to content

armgit / solr

Public Imported from GitHub
0

Apache Solr open-source search software

SOLR-15556: Add real branches for official ref-guide

Houston Putmand5ab54e70eaf
diff --git a/solr/solr-ref-guide/README.adoc b/solr/solr-ref-guide/README.adoc
index ecb833dbe96..443180a51ce 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 013f0abe5c9..d349673cf59 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")
}
}