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.

 * HTML is generated using Jekyll with these key dependencies:
 ** `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.

 NOTE: The above should install the correct version of the asciidoctor gem implicitly on a new system, but will not upgrade an existing version.
 If you experience problems building that seem unrelated to your changes, check that asciidoctor is at least v2.0.10 or higher.
 This is usually only a problem if you have previously built the ref guide prior to October 2019 or used asciidoctor for some other reason.
 `gem info asciidoctor` will show you what version(s) you have installed.


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

	* HTML is generated using Jekyll with these key dependencies:
	** `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.

	NOTE: The above should install the correct version of the asciidoctor gem implicitly on a new system, but will not upgrade an existing version.
	If you experience problems building that seem unrelated to your changes, check that asciidoctor is at least v2.0.10 or higher.
	This is usually only a problem if you have previously built the ref guide prior to October 2019 or used asciidoctor for some other reason.
	`gem info asciidoctor` will show you what version(s) you have installed.


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