lucene/solr/solr-ref-guide
Joel Bernstein 70f001918e SOLR-11943: Fix RefGuide for latlonVectors and haversineMeters functions. 2018-09-09 20:59:13 -04:00
..
src SOLR-11943: Fix RefGuide for latlonVectors and haversineMeters functions. 2018-09-09 20:59:13 -04:00
tools SOLR-12134: hook ref-guide 'bare-bones-html' validation into top level documentation target using relative javadoc URL prefixess that are now validated to point to real files 2018-04-03 16:15:09 -07:00
README.adoc Ref Guide: add step to install asciidoctor before jekyll-asciidoc to prevent wrong version of gem being installed as a dependency 2018-05-17 15:03:14 -05:00
build.xml Use asciidoctor's 'attribute-missing: warn' option and fix some places that were generating warnings because of unescaped/uninteded attribute syntax 2018-04-05 17:16:00 -07:00
ivy.xml SOLR-7887: Upgrade Solr to use log4j2 -- log4j 1 now officially end of life 2018-03-25 19:16:09 -07:00

README.adoc

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

* Via Jekyll to build an HTML browsable version of the Ref Guide.
** Prerequisites: `Ruby` (v2.1 or higher) and 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 Jekyll 3.5.0.
*** `asciidoctor`: v1.5.6.2, not 1.5.7 or higher. Use `gem install asciidoctor --force --version 1.5.6.2`. NOTE: You must do this before installing `jekyll-asciidoc` or you'll get a version of Asciidoctor that we can't use yet.
*** `jekyll-asciidoc`: v2.1 or higher. Use `gem install jekyll-asciidoc` to install.
*** `pygments.rb`: v1.1.2 or higher. Use `gem install pygments.rb` to install.
* Via `asciidoctor-ant` to build the officially released PDF version of the Ref Guide.
** Prerequisites: None beyond those required to use the main Lucene/Solr build: Java, and Ant.

== Building the Guide
For details on building the ref guide, see `ant -p`.

There are currently four available targets:

* `ant default`: builds both the PDF and HTML versions of the Solr Ref Guide.
* `ant build-site`: builds only the HTML version.
* `ant build-pdf`: builds only the PDF 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 & pdf 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
* `../build/solr-ref-guide/apache-solr-ref-guide-X.Y.pdf` - PDF 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 or PDF templates.