mirror of https://github.com/apache/lucene.git
65 lines
3.2 KiB
Plaintext
65 lines
3.2 KiB
Plaintext
= 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 `src/` directory.
|
|
|
|
== Prerequisites for Building
|
|
These files are processed with AsciiDoctor in 2 different ways:
|
|
|
|
* HTML version, using Jekyll:
|
|
** `Ruby` (v2.3 or higher)
|
|
** The following gems must be installed:
|
|
*** `jekyll`: v3.5, not v4.x.
|
|
Use `gem install jekyll --force --version 3.5.0` to force install of v3.5.0.
|
|
*** `jekyll-asciidoc`: v2.1 or higher; latest version (3.0.0) is fine.
|
|
Use `gem install jekyll-asciidoc` to install.
|
|
*** `slim`: v3.0 or higher; latest version (4.0.1) is fine.
|
|
Use `gem install slim` to install.
|
|
*** `tilt`: v1.0 or higher; latest version (2.0.10) is fine.
|
|
Use `gem install tilt` to install.
|
|
*** `concurrent-ruby`: v1.0 or higher; latest version (1.1.5) is fine.
|
|
Use `gem install concurrent-ruby` to install.
|
|
|
|
|
|
== Building the Guide
|
|
For details on building the ref guide, see `gradlew tasks`, the `Documentation Tasks` section.
|
|
|
|
There are currently four available targets:
|
|
|
|
* `gradlew buildSite`: Builds an HTML Site w/Jekyll and verifies the anchors+links are valid
|
|
* `gradlew documentation`: Generate all documentation
|
|
* `gradlew javadoc`: Generates Javadoc API documentation for the main source code.
|
|
* `gradlew renderJavadoc`: Generates Javadoc API documentation for the main source code. This directly invokes javadoc tool.
|
|
* `gradlew renderSiteJavadoc`: Generates Javadoc API documentation for the site (relative links).
|
|
|
|
The output of all builds will be located in `../solr-ref-guide/build`.
|
|
|
|
== Key Directories
|
|
Key directories to be aware of:
|
|
|
|
* `src` - where all human edited `*.adoc` files related to the Guide live, as well as various configuration, theme, and template files.
|
|
* `tools` - custom Java code for parsing metadata in our `src/*.adoc` files to produce some `_data/` files for site navigation purposes.
|
|
* `../solr-ref-guide/build/content` - a copy of the `src` dir generated by gradle where:
|
|
** `*.template` files are processed to replace gradle (TODO CHECK!) properties with their runtime values
|
|
** some `../solr-ref-guide/build/content/_data` files are generated by our java tools based header attributes from each of the `*.adoc` files
|
|
* `../solr-ref-guide/build/html-site` - HTML generated version of the ref guide
|
|
|
|
See the additional documentation in `src/metadocs` for more information about how to edit files, build for releases, or modifying any Jekyll templates.
|