From 030c3c8f72be848d670b0ab8a0f7846ea9dbb086 Mon Sep 17 00:00:00 2001 From: Cassandra Targett Date: Fri, 1 Sep 2017 12:22:49 -0500 Subject: [PATCH] Ref Guide: update ref guide readme for better explanation of build dependencies and targets --- solr/solr-ref-guide/README.adoc | 32 +++++++++++++++++++++++--------- 1 file changed, 23 insertions(+), 9 deletions(-) diff --git a/solr/solr-ref-guide/README.adoc b/solr/solr-ref-guide/README.adoc index a66d79defeb..b1613965d19 100644 --- a/solr/solr-ref-guide/README.adoc +++ b/solr/solr-ref-guide/README.adoc @@ -18,26 +18,40 @@ This is the source for the Solr Reference Guide. -Raw content is stored in Asciidoc (`.adoc`) formated files in the `src/` directory. +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` and the following gems must be installed: -*** `jekyll` -*** `jekyll-asciidoc` -*** `pygments.rb` -* Via `asciidoctor-ant` to build the officially released PDF version of the Ref Guide -** Prerequisites: None (except for those required to use the Lucene/Solr build: Java, Ant) +* 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 --force --version 3.5.0 jekyll` to force install of Jekyll 3.5.0. +*** `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 realted to the Guide live, as well as various configuration, theme, and template files. +* `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.