diff --git a/solr/solr-ref-guide/src/meta-docs/publish.adoc b/solr/solr-ref-guide/src/meta-docs/publish.adoc index 010f66a7fc0..bbe551a2c6c 100644 --- a/solr/solr-ref-guide/src/meta-docs/publish.adoc +++ b/solr/solr-ref-guide/src/meta-docs/publish.adoc @@ -30,32 +30,31 @@ In order to build the Ref Guide, you must have the following: * You have checked out the Lucene/Solr source code on the machine you will be doing the release from. * You have Subversion installed. This is needed for committing the HTML files to the production website repo. -* You have installed Ruby and several gems described in the README file located at `solr/solr-ref-guide/README.adoc` in your Lucene/Solr checkout. * All builds must be done from the release branch the Guide is for. NOTE: Builds are available via https://builds.apache.org/view/L/view/Lucene/[Jenkins] for several branches. However, these HTML pages will have the `DRAFT` status noted in them and are not suitable for final production publishing. +All dependencies for the build will be installed by Gradle, no local dependencies are required. + == Build the DRAFT Guide The build process generates the page hierarchy and builds the HTML pages with custom templates the Lucene/Solr project has defined. -To build the HTML: +To build the HTML, from the top level of the project, run: -. Navigate to `./solr/solr-ref-guide`, where the Guide's `build.xml` is located. -. Run: -+ [source,bash] -$ gradlew clean buildSite -+ +$ gradlew clean solr:solr-ref-guide:buildSite + This will produce pages with a DRAFT watermark across them. While these are fine for initial DRAFT publication, see the section <> for steps to produce final production-ready HTML pages. -. The resulting Guide will be in `solr/build/solr-ref-guide`. The HTML files themselves will be in `solr/build/solr-ref-guide/html-site`. + +The resulting Guide will be in `solr/solr-ref-guide/build`. The HTML files themselves will be in `solr/solr-ref-guide/build/html-site`. == Upload to the Website Push the Guide directly to production via Subversion `import` from where you built it. [source,bash] -svn -m "Add Ref Guide for Solr 7.7" import /solr/build/solr-ref-guide/html-site https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/7_7 +svn -m "Add Ref Guide for Solr 7.7" import /solr/solr-ref-guide/build/html-site https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/7_7 Confirm you can browse to Guide manually by going to the new URL. For example: https://lucene.apache.org/solr/guide/7_7 @@ -73,11 +72,11 @@ Since the Guide has already been uploaded to SVN, you need to overwrite the exis Build the Guide locally with a parameter for the Guide version. This requires the same <> from above. [source,bash] -$gradlew clean buildSite -Dsolr-guide-version=X.Y +$gradlew clean solr:solr-ref-guide:buildSite -PsolrGuideVersion=X.Y where `X.Y` is the version you want to publish (i.e., `7.7`). -IMPORTANT: The `-Dsolr-guide-version` system property is optional if you build drafts locally or as pre-publication DRAFTs (i.e., not for publication). By default the build system uses the `lucene/version.properties` file in the current branch and assumes this is a `DRAFT` build which will have a DRAFT watermark and other labels on the pages. Including the `-Dsolr-guide-version` system property ensures the DRAFT watermark and labels are removed from the HTML files. +IMPORTANT: The `-PsolrGuideVersion` system property is optional if you build drafts locally or as pre-publication DRAFTs (i.e., not for publication). By default the build system uses the `build.gradle` file in the current branch to identify the version and assumes this is a `DRAFT` build which will have a DRAFT watermark and other labels on the pages. Including the `-PsolrGuideVersion` system property ensures the DRAFT watermark and labels are removed from the HTML files. *Pull Production Repo and Upload New Files* @@ -88,7 +87,7 @@ $ svn co https://svn.apache.org/repos/infra/websites/production/lucene/content/s + * This command checks out the Guide version directory into a local subdirectory with the same name as the version (such as "7_7"). You can provide a better name locally if you prefer by adding it to the end of the command shown above. * Don't shortcut this and download the whole production website. It will take an incredibly long time and that will feel like _forever_. -. Copy the files from the build location to the checked out Guide directory. For example, if we needed to replace the Guide for Solr 7.7, we'd do `cp -r ./solr/build/solr-ref-guide/html-site 7_7/.` +. Copy the files from the build location to the checked out Guide directory. For example, if we needed to replace the Guide for Solr 7.7, we'd do `cp -r ./solr/solr-ref-guide/build/html-site 7_7/.` . Use `svn status` to see the files modified. If there are any pages added or deleted, use `svn add ` or `svn rm ` as needed. . Commit the changes: `svn commit -m "Update production 7.7 Ref Guide"` @@ -98,7 +97,7 @@ Spot-check a few pages to verify that the DRAFT watermark is gone, and also that Solr Javadocs link back to Lucene's correctly (the UpdateRequestProcessor page has a lot of Javadoc links). -=== Make a link to the new Version from website +=== Link to the New Version from Solr Website The only edit we need to do in the website itself is adding a link to the latest guide to /solr/guide.