| = Solr Ref Guide |
| // Licensed to the Apache Software Foundation (ASF) under one |
| // or more contributor license agreements. See the NOTICE file |
| // distributed with this work for additional information |
| // regarding copyright ownership. The ASF licenses this file |
| // to you under the Apache License, Version 2.0 (the |
| // "License"); you may not use this file except in compliance |
| // with the License. You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, |
| // software distributed under the License is distributed on an |
| // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| // KIND, either express or implied. See the License for the |
| // specific language governing permissions and limitations |
| // under the License. |
| |
| 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, 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` |
| |
| See the `../../dev-docs/ref-guide` directory for information about editing and publishing the Ref Guide. |
| |
| To ignore the Ref Guide steps when running gradle `assemble` or `check`, use either `-Prefguide.include=false` or `SOLR_REF_GUIDE_INCLUDE=false`. |
| |
| 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 prerelease 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. |
| |
| **WARNING: NEVER run the "setOfficialAntoraYaml" task yourself. This is a job the release manager does as a part of the release process. |
| The dependency versions in the antora.yml will be updated at release time, it is not meant to be kept up to date between releases.** |
| |
| == Changing the UI Bundle |
| |
| Antora uses a `ui-bundle` to create a website out of the asciidoctor pages. |
| We use the https://gitlab.com/antora/antora-ui-default/[Default Antora UI] with overrides given in the `ui-src/` directory. |
| |
| 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 locally. |
| If you commit these changes to the `main` branch, then you must run a https://ci-builds.apache.org/job/Solr/job/Solr-reference-guide-ui-bundle/[Jenkins Job] to update this file in the nightlies server. |
| Once you run this job, you need to run the jenkins job to rebuild the ref-guide as well. |
| That job is run nightly, so you could also just wait. |
| |
| If you want to update, add or delete any file in `ui-src/`, please comment in-place that you are making a change. |
| If you are changing a file that already exists in the default UI, but not in `ui-src/`, download the file from the default UI repo to the correct directory under `ui-src/` first. |
| |
| You can find examples throughout the existing files in the directory. |
| Without these comments it will be extremely hard for us to rebase our local versions of the files with the upstream default Antora UI when the time comes. |