solr/solr-ref-guide/README.adoc - lucene-solr - Git at Google

 = 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.
	= 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.