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 `ant -p`.

 There are currently four available targets:

 * `ant default`: builds the HTML versions of the Solr Ref Guide.
 * `ant build-site`: also builds the HTML version.
 * `ant clean`: removes the `../build/solr-ref-guide` directory.

 The output of all builds will be located in `../build/solr-ref-guide`.

 == 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.
 * `../build/solr-ref-guide/content` - a copy of the `src` dir generated by ant where:
 ** `*.template` files are processed to replace ant properties with their runtime values
 ** some `../build/solr-ref-guide/content/_data` files are generated by our java tools based header attributes from each of the `*.adoc` files
 * `../build/solr-ref-guide/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 `ant -p`.

	There are currently four available targets:

	* `ant default`: builds the HTML versions of the Solr Ref Guide.
	* `ant build-site`: also builds the HTML version.
	* `ant clean`: removes the `../build/solr-ref-guide` directory.

	The output of all builds will be located in `../build/solr-ref-guide`.

	== 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.
	* `../build/solr-ref-guide/content` - a copy of the `src` dir generated by ant where:
	** `*.template` files are processed to replace ant properties with their runtime values
	** some `../build/solr-ref-guide/content/_data` files are generated by our java tools based header attributes from each of the `*.adoc` files
	* `../build/solr-ref-guide/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.