lucene-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cpoersc...@apache.org
Subject [35/50] lucene-solr:jira/solr-10990: Ref Guide: update ref guide readme for better explanation of build dependencies and targets
Date Wed, 06 Sep 2017 09:39:37 GMT
Ref Guide: update ref guide readme for better explanation of build dependencies and targets


Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/030c3c8f
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/030c3c8f
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/030c3c8f

Branch: refs/heads/jira/solr-10990
Commit: 030c3c8f72be848d670b0ab8a0f7846ea9dbb086
Parents: 810ae50
Author: Cassandra Targett <ctargett@apache.org>
Authored: Fri Sep 1 12:22:49 2017 -0500
Committer: Cassandra Targett <ctargett@apache.org>
Committed: Tue Sep 5 09:36:14 2017 -0500

----------------------------------------------------------------------
 solr/solr-ref-guide/README.adoc | 32 +++++++++++++++++++++++---------
 1 file changed, 23 insertions(+), 9 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/030c3c8f/solr/solr-ref-guide/README.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/README.adoc b/solr/solr-ref-guide/README.adoc
index a66d79d..b161396 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.


Mime
View raw message