This is an automated email from the ASF dual-hosted git repository.
houston pushed a commit to branch branch_9_0
in repository https://gitbox.apache.org/repos/asf/solr.git
The following commit(s) were added to refs/heads/branch_9_0 by this push:
new 2be9118 SOLR-15556: Add real branches for official ref-guide
2be9118 is described below
commit 2be9118e7d5d4c122bf5b965bdd5243d42ae634e
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.
(cherry picked from commit 8267db4f961417a9cb105f4143b45a3f3945c18d)
---
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")
}
}
