Apache
/
lucene
mirror of https://github.com/apache/lucene.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Ref Guide: update ref guide readme for better explanation of build dependencies and targets

This commit is contained in:
Cassandra Targett 2017-09-01 12:22:49 -05:00
parent 810ae50e7e
commit 030c3c8f72
1 changed files with 23 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
solr/solr-ref-guide/README.adoc
View File

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