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

SOLR-13782: Remove PDF Ref Guide build (#999) 

closes #999
This commit is contained in:
Cassandra Targett 2019-11-19 14:54:30 -07:00 committed by GitHub
parent a593d3050c
commit b5bf906caf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
19 changed files with 147 additions and 877 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
dev-tools/scripts/jenkins.build.ref.guide.sh
View File

@ -70,4 +70,4 @@ echoRun "gem install --force --version 1.1.5 concurrent-ruby"
cd solr/solr-ref-guide
set -x # Re-enable command echoing
ant clean build-site build-pdf
ant clean build-site

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

@ -36,17 +36,15 @@ Use `gem install slim` to install.
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.
* PDF version, via `asciidoctor-ant`:
** 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 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`.
@ -55,11 +53,10 @@ The output of all builds will be located in `../build/solr-ref-guide`.
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.
* `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
* `../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.
See the additional documentation in `src/metadocs` for more information about how to edit files, build for releases, or modifying any Jekyll templates.

78
solr/solr-ref-guide/build.xml
View File

@ -55,16 +55,16 @@
Basic nightly/local build of the 6.1 guide...
=> ant build-pdf
=> ant build-site
Official release build of the 6.1 guide...
Official build of the 6.1 guide...
=> ant build-pdf -Dsolr-guide-version=6.1
=> ant build-site -Dsolr-guide-version=6.1
Release of a "6.1.1" ref guide, correcting some serious error in the docs
(even if there is no 6.1.1 version - or if we've alreayd released up to 6.1.5 - of Solr itself)
(even if there is no 6.1.1 version - or if we've already released up to 6.1.5 - of Solr itself)
=> ant build-pdf -Dsolr-guide-version=6.1.1
=> ant build-site -Dsolr-guide-version=6.1.1
-->
<property name="solr-guide-version" value="${solr-docs-version}-DRAFT" />
@ -98,17 +98,13 @@
else="https://lucene.apache.org/core/${solr-docs-version-path}/">
<isset property="local.javadocs" />
</condition>
<!-- for the PDF guide, we always use absolute javadoc urls -->
<property name="pdf-solr-javadocs" value="https://lucene.apache.org/solr/${solr-docs-version-path}/" />
<property name="pdf-lucene-javadocs" value="https://lucene.apache.org/core/${solr-docs-version-path}/" />
<property name="build.content.dir" location="${build.dir}/content" />
<property name="main-page" value="index" />
<property name="pdf-filename" value="apache-solr-ref-guide-${solr-guide-version}.pdf" />
<!-- for pulling in versions of major deps -->
<property prefix="ivyversions" file="${common.dir}/ivy-versions.properties"/>
<!-- ====== TOOLS FOR GENERATING/VALIDATING BITS OF THE SITE / PDF ======= -->
<!-- ====== TOOLS FOR GENERATING/VALIDATING BITS OF THE SITE ======= -->
<property name="tools-jar-name" value="solr-ref-guide-tools.jar" />
<path id="tools-compile-classpath">
<fileset dir="lib">
@ -169,9 +165,9 @@
</copy>
</target>
<target name="build-nav-data-files" depends="build-init,build-tools-jar" description="creates nav based data files needed by both the html and pdf artifacts">
<target name="build-nav-data-files" depends="build-init,build-tools-jar" description="creates nav based data files">
<mkdir dir="${build.content.dir}/_data"/>
<java classname="BuildNavAndPDFBody"
<java classname="BuildNavDataFiles"
failonerror="true"
fork="true">
<classpath refid="tools-run-classpath"/>
@ -182,17 +178,16 @@
<macrodef name="asciidoctor-convert">
<!-- custom macro that fills in all the defaults we care about when running asciidoctor-ant
The primary purpose for this is to build the PDF, but we also use it to build a bare-bones
HTML version for validating the document structure (ie: duplicate anchors, links all point to valid anchors,
etc...) that we can't do with the generated PDF, and that we want to be able to validate
even if the current user doesn't have jekyll installed
The primary purpose for this is to build a bare-bones HTML version for validating the
document structure (ie: duplicate anchors, links all point to valid anchors,
etc...) that we want to be able to validate even if the current user doesn't have jekyll installed
-->
<attribute name="sourceDirectory"/>
<attribute name="sourceDocumentName"/>
<attribute name="outputDirectory"/>
<attribute name="backend"/>
<attribute name="solr-javadocs" default="${pdf-solr-javadocs}" />
<attribute name="lucene-javadocs" default="${pdf-lucene-javadocs}" />
<attribute name="solr-javadocs" default="${html-solr-javadocs}" />
<attribute name="lucene-javadocs" default="${html-lucene-javadocs}" />
<attribute name="headerFooter" default="true" />
<sequential>
<!-- NOTE: we have our own variant on the asciidoctor-ant task, so that sourceDocumentName=""
@ -214,12 +209,9 @@
doctype="book"
safemode="unsafe">
<attribute key="attribute-missing" value="warn" />
<attribute key="section-toc" value='' /><!-- we don't use these in the pdf -->
<attribute key="section-toc" value='' />
<attribute key="icons" value="font" />
<attribute key="icon-set" value="fa" />
<attribute key="pdf-stylesDir" value="./pdf/themes"/>
<attribute key="pdf-style" value="refguide"/>
<attribute key="pdf-fontsDir" value="./fonts"/>
<attribute key="figure-caption!" value='' />
<attribute key="idprefix" value='' />
<attribute key="idseparator" value='-' />
@ -248,36 +240,6 @@
</macrodef>
<!-- ====== PDF Build ======= -->
<target name="build-pdf" depends="bare-bones-html-validation,-build-pdf-and-reduce-pdf"
description="Builds the PDF (after building &amp; validating a bare-bones html version)" />
<target name="-build-pdf-and-reduce-pdf" depends="-build-raw-pdf,-reduce-pdf-size">
<!-- NOTE: this does everything realted to building the PDF, but skips the bare-bones-html validation -->
<echo>Finished Building ${build.dir}/${pdf-filename}</echo>
</target>
<target name="-build-raw-pdf"
depends="build-nav-data-files,resolve">
<mkdir dir="${build.dir}/pdf-tmp"/>
<asciidoctor-convert sourceDirectory="${build.content.dir}/pdf"
sourceDocumentName="SolrRefGuide-all.adoc"
outputDirectory="${build.dir}/pdf-tmp"
backend="pdf"
/>
<move file="${build.dir}/pdf-tmp/SolrRefGuide-all.pdf" tofile="${build.dir}/pdf-tmp/RAW-${pdf-filename}" />
</target>
<target name="-reduce-pdf-size" depends="build-init,build-tools-jar">
<java classname="ReducePDFSize"
failonerror="true"
fork="true">
<classpath refid="tools-run-classpath"/>
<arg value="${build.dir}/pdf-tmp/RAW-${pdf-filename}"/>
<arg value="${build.dir}/${pdf-filename}"/>
</java>
</target>
<!-- ======= HTML Site Build =======
Builds site with Jekyll.
This (for now) assumes that Jekyll (http://jekyllrb.com) is installed locally. -->
@ -297,7 +259,8 @@
depends="build-init,build-nav-data-files" >
<echo>Running Jekyll...</echo>
<exec executable="jekyll" dir="${build.content.dir}" failonerror="true">
<arg value="build"/>
<arg value="build" />
<arg value="--verbose"/>
</exec>
</target>
@ -305,7 +268,7 @@
Does a very raw converstion of the adoc files to HTML for the purpose of link & anchor checking
Unlike the "HTML Site Build" above, this does *NOT* require Jekyll, and can be done entirely
With ivy deps fetched automatically (just like the PDF)
With ivy deps fetched automatically.
-->
<target name="bare-bones-html-validation" depends="build-init,build-nav-data-files"
description="Builds (w/o Jekyll) a very simple html version of the guide and runs link/anchor validation on it">
@ -333,11 +296,8 @@
</target>
<target name="default"
description="Builds both a PDF and HTML versions of the ref guide"
depends="-build-pdf-and-reduce-pdf,build-site">
<!-- NOTE: we don't depend on build-pdf because then we'd also get the bare-bones HTML and do
link validation twice -->
<echo>PDF: ${build.dir}/${pdf-filename}</echo>
description="Builds an HTML versions of the ref guide"
depends="build-site">
<echo>SITE: ${build.dir}/html-site/${main-page}.html</echo>
</target>

1
solr/solr-ref-guide/ivy.xml
View File

@ -25,7 +25,6 @@
<dependency org="org.asciidoctor" name="asciidoctor-ant" rev="${/org.asciidoctor/asciidoctor-ant}" conf="compile" />
<dependency org="com.vaadin.external.google" name="android-json" rev="${/com.vaadin.external.google/android-json}" conf="compile" />
<dependency org="org.jsoup" name="jsoup" rev="${/org.jsoup/jsoup}" conf="compile" />
<dependency org="org.apache.pdfbox" name="pdfbox" rev="${/org.apache.pdfbox/pdfbox}" conf="compile"/>
<dependency org="org.slf4j" name="jcl-over-slf4j" rev="${/org.slf4j/jcl-over-slf4j}" conf="compile"/>
<dependency org="org.slf4j" name="slf4j-api" rev="${/org.slf4j/slf4j-api}" conf="compile"/>
<dependency org="org.slf4j" name="slf4j-simple" rev="${/org.slf4j/slf4j-simple}" conf="compile"/>

5
solr/solr-ref-guide/src/_config.yml.template
View File

@ -11,7 +11,7 @@ gems: [jekyll-asciidoc]
destination: ../html-site
# this property is useful for conditional filtering of content that is separate from the PDF.
# this property is useful for conditional filtering of content that is separate from another format (if any).
output: web
# this appears on the top navigation bar next to the home button
@ -34,7 +34,6 @@ port: 4015
exclude:
- .idea/
- .gitignore
- pdf/
# these are defaults used for the frontmatter for these file types
defaults:
@ -67,7 +66,7 @@ asciidoc: {}
# (see https://github.com/asciidoctor/jekyll-asciidoc/issues/137)
#
# NOTE: If you add any attributes here for use in adoc files, you almost certainly need to also add
# them to the <asciidoctor:convert/> ant task for building the PDF as well.
# them to the <asciidoctor:convert/> ant task for precommit validation as well.
solr-attributes: &solr-attributes-ref
solr-root-path: "../../../"
solr-guide-draft-status: "${solr-guide-draft-status}"

1
solr/solr-ref-guide/src/_includes/topnav.html
View File

@ -19,7 +19,6 @@
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Other Formats<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="https://www.apache.org/dyn/closer.cgi/lucene/solr/ref-guide" target="_blank">PDF for Latest Release</a></li>
<li><a href="https://archive.apache.org/dist/lucene/solr/ref-guide/" target="_blank">Archived PDFs</a></li>
<li><a href="https://lucene.apache.org/solr/guide/" target="_blank">Other Versions Online</a></li>
</ul>

4
solr/solr-ref-guide/src/errata.adoc
View File

@ -18,9 +18,7 @@
== Errata For This Documentation
Any mistakes found in this documentation after its release will be listed on the on-line version of this page:
https://lucene.apache.org/solr/guide/{solr-docs-version}/errata.html
Any mistakes found in this documentation after its release will be listed below.
=== Errata For Past Versions of This Documentation

13
solr/solr-ref-guide/src/how-to-contribute.adoc
View File

@ -22,13 +22,6 @@ The Lucene/Solr project has made it easy for anyone to contribute to the Solr Re
The Guide is written in simple AsciiDoc-formatted files, and the source lives in the main Lucene/Solr source repository, right alongside the code.
// This section only appears in the PDF version of the Ref Guide.
ifdef::backend-pdf[]
Find information on how to contribute to documentation online at https://lucene.apache.org/solr/guide/how-to-contribute.html.
endif::[]
// This section only appears in the HTML version of the Ref Guide.
ifdef::backend-html5[]
The following sections give an overview of how to work with AsciiDoc-format files, how our documentation is generated, and how to do a Ref Guide release.
Once you have a patch you'd like to contribute, you can submit it with a JIRA issue, the same as any other patch. See also the Solr wiki section on https://wiki.apache.org/solr/HowToContribute[How To Contribute] for information on submitting patches.
@ -39,12 +32,10 @@ include::meta-docs/asciidoc-syntax.adoc[leveloffset=+2]
include::meta-docs/editing-tools.adoc[leveloffset=+2]
== Modifying the Publication Formats
The Solr Reference Guide is published in two formats: HTML and PDF. Different tools are used for each.
The Solr Reference Guide is published in HTML format, using Jekyll and some plugins.
include::meta-docs/jekyll.adoc[leveloffset=+2]
include::meta-docs/pdf.adoc[leveloffset=+2]
== How to Publish the Guide
// This is the how to publish section:
include::meta-docs/publish.adoc[leveloffset=+1]
endif::[]

2
solr/solr-ref-guide/src/js/customscripts.js
View File

@ -56,7 +56,7 @@ $( document ).ready(function() {
} else {
// NOTE: using the "inner" HTML of the label...
// so by default we can use "bold" (or whatever) in our asciidoc and have that
// be what people see in the PDF or when javascript is disabled,
// be what people see when javascript is disabled,
// but when the pills+tabs get active, the pills won't all be bold (or whatever)
pill_a.append( label.html() );
// NOTE: Removing the label isn't strictly neccessary, but makes the pills/tabs less redundent

4
solr/solr-ref-guide/src/json-facet-api.adoc
View File

@ -186,8 +186,6 @@ include::{example-source-dir}JsonRequestApiTest.java[tag=solrj-json-terms-facet-
====
--
// TODO: This table has cells that won't work with PDF: https://github.com/ctargett/refguide-asciidoc-poc/issues/13
[width="100%",cols="20%,90%",options="header",]
|===
|Parameter |Description
@ -377,8 +375,6 @@ The output from the range facet above would look a bit like:
Range facet parameter names and semantics largely mirror facet.range query-parameter style faceting. For example "start" here corresponds to "facet.range.start" in a facet.range command.
// TODO: This table has cells that won't work with PDF: https://github.com/ctargett/refguide-asciidoc-poc/issues/13
[width="100%",cols="10%,90%",options="header",]
|===
|Parameter |Description

17
solr/solr-ref-guide/src/meta-docs/asciidoc-syntax.adoc
View File

@ -19,7 +19,7 @@
The definitive manual on AsciiDoc syntax is in the http://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual]. To help people get started, however, here is a simpler cheat sheet.
== AsciiDoc vs Asciidoctor Syntax
We use tools from the Asciidoctor project to build the HTML and PDF versions of the Ref Guide. Asciidoctor is a Ruby port of the original AsciiDoc project, which was mostly abandoned several years ago.
We use tools from the Asciidoctor project to build the HTML version of the Ref Guide. Asciidoctor is a Ruby port of the original AsciiDoc project, which was mostly abandoned several years ago.
While much of the syntax between the two is the same, there are many conventions supported by Asciidoctor that did not exist in AsciiDoc. While the Asciidoctor project has tried to provide back-compatibility with the older project, that may not be true forever. For this reason, it's strongly recommended to only use the Asciidoctor User Manual as a reference for any syntax that's not described here.
@ -66,9 +66,9 @@ More info: http://asciidoctor.org/docs/user-manual/#source-code-blocks
=== Source Block Syntax Highlighting
The PDF and HTML outputs use Pygments to add syntax highlighting to code examples. This is done by adding the language of the code block after the `source`, as shown in the above example source block (`xml` in that case).
The HTML output uses Rouge to add syntax highlighting to code examples. This is done by adding the language of the code block after the `source`, as shown in the above example source block (`xml` in that case).
Pygments has a long selection of lexers available. You can see the full list at http://pygments.org/docs/lexers. Use one of the valid short names to get syntax highlighting for that language.
Rouge has a long selection of lexers available. You can see the full list at https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers. Use one of the valid short names to get syntax highlighting for that language.
Ideally, we will have an appropriate lexer to use for all source blocks, but that's not possible. When in doubt, choose `text`, or leave it blank.
@ -88,7 +88,7 @@ Snippets can be included directly from any file in the Lucene/Solr GIT repo by r
----
--
When building the PDF or HTML versions of the Guide, the `solr-root-path` attribute will be automatically set correctly for the (temporary) `build/solr-ref-guide/content` directory used by Ant.
When building the Guide, the `solr-root-path` attribute will be automatically set correctly for the (temporary) `build/solr-ref-guide/content` directory used by Ant.
In order for editors (such as ATOM) to be able to offer "live preview" of the `*.adoc` files using these includes, the `solr-root-path` attribute must also be set as a document level attribute in each file, with the correct relative path.
@ -128,7 +128,7 @@ Titles can be added to most blocks (images, source blocks, tables, etc.) by simp
== Links
=== Link to Sites on the Internet
When converting content to HTML or PDF, Asciidoctor will automatically render many link types (such as `http:` and `mailto:`) without any additional syntax.
When converting content to HTML, Asciidoctor will automatically render many link types (such as `http:` and `mailto:`) without any additional syntax.
However, you can add a name to a link by adding the URI followed by square brackets:
@ -188,9 +188,8 @@ To link to this section, there are two approaches depending on where you are lin
==== Link to Another Page
To link to _another page_ or a section on another page, you must refer to the full filename and refer to the section you want to link to.
Unfortunately, when you want to refer the reader to another page without deep-linking to a section, you cannot simply put the other file name in angle brackets and call it a day. This is due to the PDF conversion - once all the pages are combined into one big page for one big PDF, the lack of a specific reference causes inter-page links to fail.
So, *you must always link to a specific section*. If all you want is a reference to the top of another page, you can use the implicit `id` of the page -- the filename w/o the `.adoc` extension -- as your anchor reference.
Unfortunately, when you want to refer the reader to another page without deep-linking to a section, you cannot simply put the other file name in angle brackets and call it a day.
*You must always link to a specific section*. If all you want is a reference to the top of another page, you can use the implicit `id` of the page -- the filename w/o the `.adoc` extension -- as your anchor reference.
Example::
To construct a link to the `upgrading-solr.adoc` page, we need to refer to the file name (`upgrading-solr.adoc`), then use the page id (`upgrading-solr`) as the anchor reference. As in:
@ -365,7 +364,7 @@ AsciiDoc supports several types of callout boxes, called "admonitions":
* CAUTION
* WARNING
It is enough to start a paragraph with one of these words followed by a colon (such as `NOTE:`). When it is converted to HTML or PDF, those sections will be formatted properly - indented from the main text and showing an icon inline.
It is enough to start a paragraph with one of these words followed by a colon (such as `NOTE:`). When it is converted to HTML, those sections will be formatted properly - indented from the main text and showing an icon inline.
You can add titles to admonitions by making it an admonition block. The structure of an admonition block is like this:

5
solr/solr-ref-guide/src/meta-docs/jekyll.adoc
View File

@ -31,7 +31,7 @@ The following sections describe the main features of Jekyll that you will encoun
=== Jekyll-Asciidoctor Plugin
We use a plugin for Jekyll from the Asciidoctor project to integrate Jekyll with Asciidoc formatted content. The source for the plugin is available at https://github.com/asciidoctor/jekyll-asciidoc.
This plugin allows us to use Asciidoctor-style variables with Jekyll, instead of having to maintain two sets of the same variables (one for HTML version and another for PDF version).
This plugin allows us to use Asciidoctor-style variables with Jekyll.
=== _config.yml
@ -49,7 +49,7 @@ Many guides to Jekyll also say that defining the layout in the front matter is r
The Solr Ref Guide uses the front matter to define some custom attributes on a per page basis:
* `page-children` - ordered list of child pages, this is used to build the site navigation menu that appears to the left of each page's content (and to order the pages in the PDF)
* `page-children` - ordered list of child pages, this is used to build the site navigation menu that appears to the left of each page's content.
Other page-level elements can also be defined, such as an Asciidoctor attribute that should apply only to that page, but are not needed on a regular basis.
@ -193,7 +193,6 @@ My content...
--
----
. Because these tabbed sections are created when the HTML and related JavaScript is loaded, when the PDF is generated it will ignore all the class and ID information in the page because it is meaningless to it (asciidoctor-pdf does not recognize roles/custom classes). In the PDF, this content will be displayed in Example Blocks, which have some formatting rules, but will not be shown as tabs and shouldn't show any other oddities.
== Building the HTML Site

145
solr/solr-ref-guide/src/meta-docs/pdf.adoc
View File

@ -1,145 +0,0 @@
= Making Changes to the PDF Version
// 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.
The main published artifact of the Solr Reference Guide is a PDF document.
The PDF version of the Ref Guide uses `asciidoctor-pdf` (indirectly) to convert the `.adoc` files to PDF.
In order for all of the various files to be converted into a single, large, PDF file, another `.adoc` file must be created.
== About asciidoctor-pdf
Our PDF build process uses the https://github.com/asciidoctor/asciidoctor-ant[`asciidoctor-ant`] project to integrate Asciidoctor.
The `asciidoctor-ant` project is really an Ant wrapper around https://github.com/asciidoctor/asciidoctorj[`asciidoctorj`]. This is a Java binding of several Asciidoctor projects that produces a .jar that includes Asciidoctor, Asciidoctor PDF and Asciidoctor EPub.
Since it is a binding for the Ruby implementations of these three projects, they each work the same way they would if we were using the Ruby versions.
== Configuring the PDF Theme
Nearly all of the styling and layout of the PDF is controlled by a single YAML file that is called a theme.
See the section <<Modifying the Theme>> for information on how to update the theme.
=== Declaring the Theme to Use
Our theme is `refguide-theme.yml`, found in `solr/solr-ref-guide/pdf/themes`.
New themes must be named to include `-theme.yml` at the end. They must also be in proper YAML format.
The theme to use when generating the PDF is defined with the `pdf-style` attribute. Only the first part of the file name is used. So, a theme file named `refguide-theme.yml` is selected by defining `pdf-style=refguide`.
In the section <<Asciidoctor PDF Attributes>> below, we can see how we've declared this in our Ant target.
=== Modifying the Theme
All of the styling capabilities are described in the https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc[Asciidoctor PDF Theming Guide].
== About the Uber-Document
In order for all of the files in `.adoc` format to be compiled into a single PDF, we need to give the process one `.adoc` file (an "uber-document") that includes all of the content we want in the PDF. In other words, there is no command that says "take all the files in this directory and make one PDF".
Asciidoctor has a nice feature called the _include directive_, which allows you to insert content from another file into the current file (more details in the http://asciidoctor.org/docs/user-manual/#include-directive[Asciidoctor documentation]).
We wanted to make sure we didn't add to the burden of maintaining the PDF by asking everyone to update the uber-document or trying to institute some sort of check on if all the pages are included and in the right place in the hierarchy. Instead, the uber-document is build programmatically at build time.
The uber-document is found in `solr/solr-ref-guide/src/pdf/SolrRefGuide-all.adoc`. This document is very simple - it includes only the Apache license statement and a single `include` directive to another file:
[source]
\include::_data/pdf-main-body.adoc[]
The Ant target `build-pdf` includes a dependency on another target, `build-nav-data-files`. This target looks at each document and builds the `pdf-main-body.adoc` file with the proper hierarchy of all pages.
NOTE: You will not see the `pdf-main-body.adoc` in `solr/solr-ref-guide/src/_data` directory. This file exists only once it has been built, and it is placed in the build directory, at `solr/solr-ref-guide/build/content_data`.
== Configuring the build-pdf Ant Target
Since most of the styling and layout is defined by the theme, the options that must be configured in the Ant target relate to where to find referenced files, font directories, image directories, and similar top-level document settings.
There are two types of settings at work in our Ant target. First are the settings which are part of the `asciidoctor-ant` jar. Second, we are able to declare any Asciidoctor PDF attribute (setting) that we want to apply to the entire PDF.
Our Ant target (`build-pdf`) uses the following settings:
[source,xml]
----
<asciidoctor:convert
sourceDirectory="${build.content.dir}/pdf"
sourceDocumentName="SolrRefGuide-all.adoc"
baseDir="${build.content.dir}"
outputDirectory="${build.dir}"
backend="pdf"
extensions="adoc"
sourceHighlighter="coderay"
embedAssets="true"
imagesDir="${build.content.dir}"
doctype="book"
safemode="unsafe">
<attribute key="icons" value="font" />
<attribute key="icon-set" value="fa" />
<attribute key="pdf-stylesDir" value="./pdf/themes"/>
<attribute key="pdf-style" value="refguide"/>
<attribute key="pdf-fontsDir" value="./pdf/fonts"/>
<attribute key="pagenums" value='' />
<attribute key="figure-caption!" value='' />
<attribute key="idprefix" value='' />
<attribute key="idseparator" value='-' />
<!-- attributes used in adoc files -->
<!-- NOTE: If you add any attributes here for use in adoc files, you almost certainly need to also add
them to the _config.yml.template file for building the jekyll site as well
-->
<!-- ... -->
</asciidoctor:convert>
----
There are a lot of options here. Note that some include the `<attribute>` tag and some do not. Those that do not are options provided by `asciidoctor-ant` so don't need any special syntax. The options with the `<attribute>` tag are not provided by `asciidoctor-ant` but are supported by `asciidoctor-pdf` so will be applied when the target is run. A few of these are custom variables that we have defined ourselves.
=== Asciidoctor Ant Attributes
`sourceDirectory="${build.content.dir}/pdf"`:: Defines where to find the source file to build the PDF. The variable is declared earlier in `build.xml`.
`sourceDocumentName="SolrRefGuide-all.adoc"`:: The source file name, which in our case will be built as described in the section <<About the Uber-Document>>.
`baseDir="${build.content.dir}"`:: The root path for any included files.
`outputDirectory="${build.dir}"`:: Defines where the resulting PDF file should go. In this case, the
`backend="pdf"`:: The output format. The `asciidoctor-ant` jar is also capable of outputting DocBook format, so we must declare we want a PDF.
`extensions="adoc"`:: The file extensions to allow for the source document.
`sourceHighlighter="coderay"`:: The library to use for syntax highlighting source code.
`imagesDir="${build.content.dir}"`:: The directory to use to find images referenced in the documents.
`doctype="book"`:: Adds support for book-style format and sections, such as a preface, colophon, glossary, index, etc.
`safemode="unsafe">`:: Allows including resources that are external to the parent directory of the source file. For example, source examples could be pulled from Solr's source code instead of copied to documentation. This setting allows that to happen.
=== Asciidoctor PDF Attributes
`<attribute key="icons" value="font" />`:: The style of icons.
`<attribute key="icon-set" value="fa" />`:: The icon set to use. We use the Font Awesome font set.
`<attribute key="pdf-stylesDir" value="./pdf/themes"/>`:: The directory to find PDF themes. See the section <<Configuring the PDF Theme>> for more details on themes.
`<attribute key="pdf-style" value="refguide"/>`:: The theme to use. The theme must be saved in the directory referenced with the `pdf-stylesDir` attribute, and must be named `<pdf-style>-theme.yml`.
`<attribute key="pdf-fontsDir" value="./pdf/fonts"/>`:: The directory where to find fonts declared in the theme.
`<attribute key="figure-caption!" value='' />`:: Sets caption labels and numbers (such as "Figure 1") to block images. The exclamation at the end of this setting in our config _disables_ figure captioning.
`<attribute key="idprefix" value='' />`:: Sets the prefix for auto-generated section IDs, such as those from headings in a page. In our config, this is effectively "null", so auto-generated section IDs do not have any prefix.
`<attribute key="idseparator" value='-' />`:: Sets the separator between words in auto-generated section IDs to a hyphen (`-`).
=== Custom Attributes
These attributes use variables that are inserted by Ant during the PDF creation process. This allows us to pull from standard Lucene/Solr build files, and not have to update several places for any release. The Ant build process updates the `_config.yml` file from the `_config.yml.template`, then these attributes pull the proper value from that file.
`<attribute key="solr-guide-draft-status" value="${solr-guide-draft-status}" />`:: Indicates if this is a `DRAFT` PDF or not.
`<attribute key="solr-guide-version" value="${solr-guide-version}" />`:: The version of the Guide itself.
`<attribute key="solr-docs-version" value="${solr-docs-version}" />`:: The version of Solr covered by this guide.
`<attribute key="solr-javadocs" value="${solr-javadocs}" />`:: Sets the path for Solr javadoc links to include the right path for the current release version.
`<attribute key="lucene-javadocs" value="${lucene-javadocs}" />`:: Sets the path for Lucene javadoc links to the right path for the current release version.
`<attribute key="build-date" value="$\{DSTAMP}" />`:: Sets the date of the build to add the date to the footer of each page of the PDF.
`<attribute key="build-year" value="${current.year}" />`:: Sets the year of the build to add the date to the copyright notice.

236
solr/solr-ref-guide/src/meta-docs/publish.adoc
View File

@ -16,114 +16,77 @@
// specific language governing permissions and limitations
// under the License.
The PDF version of the Guide is the *official* release, and requires a vote before release.
This section details how to build the Guide for publication.
The HTML version is considered a "convenience" version, and does not require a vote.
== Guide Publication Overview
It's strongly preferred that both PDF and HTML versions are available during the vote for the PDF. However, since the HTML version is not an official release, it is more of an unwritten rule to publish the HTML at the same time as producing a release candidate for the PDF.
IMPORTANT: These instructions assume you have the proper dependencies for building HTML and are publishing both versions simultaneously. See <<Additional Pre-Requisites for HTML>> for details.
. Build and publish the DRAFT version.
. Continue to update docs as needed while Lucene/Solr artifact VOTE thread is ongoing.
. After VOTE has passed, build and publish final version to overwrite DRAFT watermarked pages.
== Pre-Requisites
The PDF version of the Solr Reference Guide is the *official* version. As such, it is voted on by the community before release, and is treated as an official artifact of the Lucene/Solr project.
In order to build the Ref Guide, you must have the following:
=== Pre-Requisites for PDF
* You have checked out the Lucene/Solr source code on the machine you will be doing the release from.
* You have Subversion installed. This is needed for committing the HTML files to the production website repo.
* You have installed Ruby and several gems described in the README file located at `solr/solr-ref-guide/README.adoc` in your Lucene/Solr checkout.
* All builds must be done from the release branch the Guide is for.
The build process downloads the required .jar to build the PDF version, so the only pre-requisites are for the publication process:
NOTE: Builds are available via https://builds.apache.org/view/L/view/Lucene/[Jenkins] for several branches. However, these HTML pages will have the `DRAFT` status noted in them and are not suitable for final production publishing.
* You have checked out the Lucene/Solr source code on the machine you will be doing the release from. You will need scripts in the `dev-tools` directory.
* You have generated a GPG key. See the Apache documentation on https://www.apache.org/dev/release-signing.html#generate[generating a code signing key].
* You have Python 3 installed. This is needed to poll the mirrors after release to be sure it's propagated enough to make the announcement.
* You have Subversion installed. This is needed for committing the PDF to `dist/dev` and `dist/releases` repos.
== Build the DRAFT Guide
=== Additional Pre-Requisites for HTML
The build process generates the page hierarchy and builds the HTML pages with custom templates the Lucene/Solr project has defined.
To build the PDF locally, you need several required dependencies, listed in `solr-ref-guide/README.adoc`. If you do not have these dependencies locally, you cannot build and publish the Ref Guide.
To build the HTML:
NOTE: Builds are available via Jenkins for several branches. However, these HTML pages will have the `DRAFT` status noted in them and will not be suitable for publishing.
== Generate the PDF & HTML
No local dependencies are required to build the PDF. The Ant target will download the jars and other items it requires.
The build process generates the PDF, including the page hierarchy, and then runs an optimization script on the PDF to make it smaller.
To build the PDF:
. Run `ant clean default -Dsolr-guide-version=X.Y`, where `X.Y` is the version you want to publish (i.e., `7.4`).
. The resulting PDF will be in `solr/build/solr-ref-guide`. The HTML files will be in `solr/build/solr-ref-guide/html-site`.
IMPORTANT: The `-Dsolr-guide-version` system property is optional. By default the build system uses the `version.properties` of the current branch and assumes this is a `DRAFT` build. Including this system property ensures the DRAFT watermark and labels are removed from the HTML files.
== Prepare & Upload Release Candidate
=== Upload PDF to dist/dev
The `dist/dev` Subversion repository includes a directory for the Solr Ref Guide at https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/[`lucene/solr/ref-guide`] which can host the release candidate (RC) during the VOTE stage of the process.
These steps walk through checking out this directory and uploading the Guide to it.
. Checkout the directory: `svn co https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide solr-ref-guide-rc`
* If you have already checked out this directory, you can simply update it: `svn update solr-ref-guide-rc`
. Change directories so `solr-ref-guide-rc` is your working directory (`cd solr-ref-guide-rc`).
IMPORTANT: The next step requires that you have already generated your GPG keys. Your GPG passphrase will be required.
[start=3]
. Run the Prep Ref Guide script to prepare the RC. This script ensures proper naming of the PDF file, generates
`.sha512` and `.asc` files and creates the proper RC sub-directories under `solr-ref-guide-rc`.
.. The structure of the input is: `prep-solr-ref-guide-rc.sh <path/PDFfilename> <Solrversion-RC#> GPGkey`.
.. From the `solr-ref-guide-rc` directory, it will look something like this:
. Navigate to `./solr/solr-ref-guide`, where the Guide's `build.xml` is located.
. Run:
+
[source,bash]
----
$ ~/lucene-source/dev-tools/scripts/prep-solr-ref-guide-rc.sh apache-solr-ref-guide-7.0.pdf 7.0-RC0
+ mkdir apache-solr-ref-guide-7.0-RC0
+ mv apache-solr-ref-guide-7.0.pdf apache-solr-ref-guide-7.0-RC0/apache-solr-ref-guide-7.0.pdf
+ cd apache-solr-ref-guide-7.0-RC0
+ shasum -a 512 apache-solr-ref-guide-7.0.pdf
+ gpg -u DEADBEEF --armor --output apache-solr-ref-guide-7.0.pdf.asc --detach-sig apache-solr-ref-guide-7.0.pdf
You need a passphrase to unlock the secret key for
user: "Your Name <you@apache.org>"
4096-bit RSA key, ID DEADBEEF, created 1969-07-04
----
$ ant clean default
+
. Add and commit the new release candidate to the `dist/dev` with these steps:
.. `svn add apache-solr-ref-guide-7.0-RC0`
.. `svn commit -m "7.0 ref guide RC0"`
This will produce pages with a DRAFT watermark across them. While these are fine for initial DRAFT publication, see the section <<Publish the Guide>> for steps to produce final production-ready HTML pages.
. The resulting Guide will be in `solr/build/solr-ref-guide`. The HTML files themselves will be in `solr/build/solr-ref-guide/html-site`.
== Upload to the Website
=== Upload HTML Files
// A lot of this was copied from https://wiki.apache.org/lucene-java/ReleaseTodo#Website_.2B-.3D_javadocs. See that section for explanations for why some steps are required.
==== Step 1: Update extpaths.txt in CMS Staging
*Step 1: Update extpaths.txt in CMS Staging*
. Checkout CMS trunk:
+
[source,bash]
svn co --depth=immediates https://svn.apache.org/repos/asf/lucene/cms/trunk/content website-source
$ svn co --depth=immediates https://svn.apache.org/repos/asf/lucene/cms/trunk/content website-source
+
* If you already have this repo checked out, you can simply `svn up website-source` to update to the latest revision.
. `cd website-source`
. Add Guide branch dir: `echo solr/guide/X_Y >> extpaths.txt`
. `$ cd website-source` (where you just checked out the repo)
. Add the path for the new Guide version:
+
[source,bash]
$ echo solr/guide/X_Y >> extpaths.txt
+
where `X_Y` is the new version (i.e, `7_7`)
. Commit changes:
+
[source,bash]
svn commit -m "Update CMS production sync exceptions for X_Y_Z Guide" extpaths.txt
$ svn commit -m "Update CMS production sync exceptions for X_Y_Z Guide" extpaths.txt
==== Step 2: Push Guide to Website Production
*Step 2: Push Guide to Website Production*
Go to the checkout directory where you have built the Guide and push the documentation via subversion import. You must push it to the path you just added to `extpaths.txt`, so if the path you added was `solr/guide/6_5`, you'll use the path as shown in the below example:
Push the Guide directly to production via Subversion `import` from where you built it.
You must push it to the path you just added to `extpaths.txt`, so if the path you added was `solr/guide/7_7`, you'll use the path as shown in the below example:
[source,bash]
svn -m "Add Ref Guide for Solr 6.5" import <checkoutroot>/solr/build/solr-ref-guide/html-site https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/6_5
svn -m "Add Ref Guide for Solr 7.7" import <checkoutroot>/solr/build/solr-ref-guide/html-site https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/7_7
Confirm you can browse to these URLs manually, and especially that Solr javadocs link back to lucene's correctly. Example:
https://lucene.apache.org/solr/guide/6_5
Confirm you can browse to Guide manually by going to the new URL. For example:
https://lucene.apache.org/solr/guide/7_7
==== Step 3: Push Staging extpaths.txt to Production
*Step 3: Push Staging extpaths.txt to Production*
The `extpaths.txt` works by listing paths that should be ignored when the CMS syncs the staging and production repositories. Publishing staging to production will only succeed if the paths listed in `extpaths.txt` exist in production. At the same time, if a path exists in production but not in staging it will be deleted unless it is defined in `extpaths.txt`.
@ -131,65 +94,48 @@ After pushing the content to production, check that the `extpaths.txt` in produc
Production URL: https://lucene.apache.org/extpaths.txt
== Hold a VOTE
Votes must be sent to the lucene-dev mailing list (`dev@lucene.apache.org`).
. Send an email to `dev@lucene.apache.org` with subject, "VOTE: Release Apache Solr Ref Guide for Solr X.Y".
. The body of the email should include the full URL of the RC directory in the `dist/dev` repo. Such as: https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-7.0-RC0
. You can add your own +1 to the vote announcement email.
. If there are issues that need to be resolved, you can start the process over, using RC1, RC2, etc., as needed.
NOTE: Ideally, the HTML version will also be available for voters to review.
== Publish the Guide
=== Move the PDF to dist/releases
There are two steps to publishing the Guide: first, uploading the DRAFT pages with the production-ready version; and second, updating links to point to the new Guide.
Once at least three PMC members have voted for release (see https://www.apache.org/foundation/voting.html#ReleaseVotes[Apache Voting Process] for details on the rules for votes), the release candidate can be released.
=== Update DRAFT for Release
. Use the Publish Solr Ref Guide script (`publish-solr-ref-guide.sh`) to generate the proper SVN commands to be run to execute a remote move of the RC files to the final `dist/releases` repository.
.. The script takes only the version and _RC number that passed the vote_ as inputs, such as `7.0-RC0`.
.. The input and output of the script will look like this:
Since the Guide has already been published, you need to update the production
website repository and overwrite the existing files:
*Build Production Guide*
Build the Guide locally with a parameter for the Guide version. This requires the same <<Pre-Requisites,pre-requisites>> from above.
[source,bash]
$ant clean default -Dsolr-guide-version=X.Y
where `X.Y` is the version you want to publish (i.e., `7.7`).
IMPORTANT: The `-Dsolr-guide-version` system property is optional if you build drafts locally or as pre-publication DRAFTs (i.e., not for publication). By default the build system uses the `lucene/version.properties` file in the current branch and assumes this is a `DRAFT` build which will have a DRAFT watermark and other labels on the pages. Including the `-Dsolr-guide-version` system property ensures the DRAFT watermark and labels are removed from the HTML files.
*Pull Production Repo and Upload New Files*
. Checkout the directory you need to update from the production repo:
+
[source,bash]
----
$ ~/lucene-source/dev-tools/scripts/publish-solr-ref-guide-rc.sh X.Y-RCZ
## Run the following commands when ready...
svn move -m 'publishing apache-solr-ref-guide-X.Y-RCZ' https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RCZ/apache-solr-ref-guide-X.Y.pdf https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RCZ/apache-solr-ref-guide-X.Y.pdf.asc https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RCZ/apache-solr-ref-guide-X.Y.pdf.sha512 https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/
svn rm -m 'cleaning up apache-solr-ref-guide-X.Y-RCZ' https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RCZ
----
[start=2]
. The release should propagate to as many mirrors as possible before announcing the release, generally 24 hours is long enough. Use the Poll Mirrors script (`poll-mirrors.py`) to check the status:
$ svn co https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/<dir>
+
[source,bash]
python3 -u ~/lucene-source/dev-tools/scripts/poll-mirrors.py -details -p lucene/solr/ref-guide/apache-solr-ref-guide-X.Y.pdf
* This command checks out the Guide version directory into a local subdirectory with the same name as the version (such as "7_7"). You can provide a better name locally if you prefer by adding it to the end of the command shown above.
* Don't shortcut this and download the whole production website. It will take an incredibly long time and that will feel like _forever_.
. Copy the files from the build location to the checked out Guide directory. For example, if we needed to replace the Guide for Solr 7.7, we'd do `cp -r ./solr/build/solr-ref-guide/html-site 7_7/.`
. Use `svn status` to see the files modified. If there are any pages added or deleted, use `svn add <file>` or `svn rm <file>` as needed.
. Commit the changes: `svn commit -m "Update production 7.7 Ref Guide"`
* This script requires Python 3 to be installed on your machine.
* If you have over 85% of the mirrors with the file, it's OK to go ahead with the announcement.
. You may get an automated email about updating the ASF release repository; you can safely ignore this email.
*Verify Upload Successful*
=== Archive Old PDF Versions
. The `dist/releases` repo is only meant to keep the latest releases. Shortly after new releases are mirrored, they are copied to `archive.apache.org`, so older releases can safely be deleted from `dist/releases` since they have been backed up in the archives.
.. Run the Archive Ref Guide script (`archive-solr-ref-guide.sh`) using the X.Y version of the Ref Guide that has just been published. Older RCs will also be removed.
.. Again, this script doesn't do any direct removal of files, it only outputs SVN commands for you to copy and paste:
+
[source,bash]
----
$ ~/lucene-source/dev-tools/scripts/archive-solr-ref-guide.sh X.Y
## Run the following commands when ready...
# Delete old releases
svn rm -m 'removing archived ref guide files prior to X.Y' https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/apache-solr-ref-guide-A.B.pdf https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/apache-solr-ref-guide-A.B.pdf.asc https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/apache-solr-ref-guide-A.B.pdf.sha512
# Delete old RC files
svn rm -m 'cleaning up old RCs now that X.Y has been released' https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RC0/ https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RC1/
----
Spot-check a few pages to verify that the DRAFT watermark is gone, and also
that Solr Javadocs link back to Lucene's correctly (the UpdateRequestProcessor
page has a lot of Javadoc links).
=== Make New HTML Version the Default
When the PDF is announced as available, the HTML version should already be available on the Solr website. There are a few steps to take to make the new HTML version the default.
There are a few steps to take to make the new HTML version the default.
TIP: You can use the CMS system for these changes, or you can edit the file locally and commit it to the staging repo.
@ -197,46 +143,6 @@ TIP: You can use the CMS system for these changes, or you can edit the file loca
. Update the Guide redirect rule that looks like the below in `content/.htaccess` so URLs without a version in the path are redirected to the latest available version.
+
[source,text]
RedirectMatch temp /solr/guide/(?!index.html)([a-z].*) /solr/guide/7_0/$1
RedirectMatch temp /solr/guide/(?!index.html)([a-z].*) /solr/guide/7_7/$1
+
In the above example, you would change the `7_0` part of the path to the right version (`7_1`, etc.).
== Announce the Release
Announce the availability of the new Ref Guide on `solr-user@lucene.apache.org` and CC `general@lucene.apache.org` and `announce@apache.org`.
WARNING: You must send the announcement email from your @apache.org email address or announce@apache will reject it.
Always use the link to the download redirector for the announcement, as it will automatically direct users to the closest mirror for download: `https://www.apache.org/dyn/closer.cgi/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y.pdf`.
You should include a link to the HTML version in your announcement.
.Sample announcement
[source,text]
----
The Lucene PMC is pleased to announce that the Solr Reference Guide
for 7.0 is now available.
This 1,035-page PDF is the definitive guide to using Apache Solr, the
search server built on Lucene.
The PDF Guide can be downloaded from:
https://www.apache.org/dyn/closer.cgi/lucene/solr/ref-guide/apache-solr-ref-guide-7.0.pdf.
It is also available online at https://lucene.apache.org/solr/guide/7_0.
----
If the Guide is being published more than a day or two after the application itself, you should update the Solr website news page with the announcement (https://lucene.apache.org/solr/news.html).
== Updating HTML Files after Publication
If you need to re-publish an existing online copy of the Guide, you will need to checkout the directory in production website repository and overwrite the existing files:
. Build the new HTML files locally (`ant clean build-site`), or download them from Jenkins.
. Checkout the directory you need to update from the production repo: `svn co https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/<dir>`.
* This command checks out the Guide version directory into a local subdirectory with the same name as the version (such as "6_5"). You can provide a better name locally if you prefer by adding it to the end of the command shown above.
* Don't shortcut this and download the whole production website. It will take an incredibly long time and that will feel like _forever_.
. Copy the files from the build location to the checked out Guide directory. For example, if we needed to replace the current Guide for Solr 6.5, we'd do `cp -r <checkoutroot>/solr/build/html-site 6_5/.`
. Use `svn status` to see the files modified.
. If there are any pages added or deleted, use `svn add <file>` or `svn rm <file>` as needed.
. Commit the changes: `svn commit -m "Update production 6.5 Ref Guide"`
In the above example, you would change the `7_7` part of the path to the right version (`8_0`, etc.).

36
solr/solr-ref-guide/src/pdf/SolrRefGuide-all.adoc
View File

@ -1,36 +0,0 @@
= Apache Solr Reference Guide: For Solr {solr-guide-version}
:toc:
:toc-title: Table of Contents
:toclevels: 1
:author: Written by the Apache Lucene/Solr Project
:email: https://lucene.apache.org/solr
:revdate: Published {build-date}
:experimental:
// 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.
[discrete]
= Licenses
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.
Apache and the Apache feather logo are trademarks of The Apache Software Foundation. Apache Lucene, Apache Solr and their respective logos are trademarks of the Apache Software Foundation. Please see the http://www.apache.org/foundation/marks/[Apache Trademark Policy] for more information.
<<<
include::_data/pdf-main-body.adoc[]

260
solr/solr-ref-guide/src/pdf/themes/refguide-theme.yml
View File

@ -1,260 +0,0 @@
font:
catalog:
# Noto Sans supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols
# Noto Sans used for body text
Noto Sans:
normal: Noto_Sans/NotoSans-Regular.ttf
bold: Noto_Sans/NotoSans-Bold.ttf
italic: Noto_Sans/NotoSans-Italic.ttf
bold_italic: Noto_Sans/NotoSans-BoldItalic.ttf
# Inconsolata used for monospaced text & code blocks
Inconsolata:
normal: Inconsolata/Inconsolata-Regular.ttf
bold: Inconsolata/Inconsolata-Bold.ttf
italic: Inconsolata/Inconsolata-Regular.ttf
bold_italic: Inconsolata/Inconsolata-Bold.ttf
# M+1mn is from the asciidoctor-pdf project
# Provides the glyphs for callout numbers (see conum section below)
# This is a fallback font, and will only be used when it can fill in missing glyphs from other fonts
M+1mn Fallback:
normal: mplus1mn/mplus1mn-regular-ascii-conums.ttf
bold: mplus1mn/mplus1mn-bold-ascii.ttf
italic: mplus1mn/mplus1mn-italic-ascii.ttf
bold_italic: mplus1mn/mplus1mn-bold_italic-ascii.ttf
fallbacks:
- M+1mn Fallback
# page-level settings apply to the entire page
page:
background_color: '#ffffff'
layout: portrait
margin: [0.5in, 0.75in, 0.75in, 0.67in]
size: LETTER
# base-level settings are defaults for other elements
base:
align: left
# color as hex string (leading # is optional)
font_color: '#333333'
font_family: Noto Sans
font_size: 10
line_height_length: 11
line_height: $base_line_height_length / $base_font_size
font_size_large: round($base_font_size * 1.25)
font_size_small: round($base_font_size * 0.85)
font_size_min: $base_font_size * 0.75
font_style: normal
border_color: '#eeeeee'
border_radius: 4
border_width: 0.5
vertical_rhythm: 10
horizontal_rhythm: $base_line_height_length
vertical_spacing: $vertical_rhythm
link:
font_color: '#428bca'
# literal is used for inline monospaced strings in prose and in table cells
literal:
font_color: '#333333'
font_family: Inconsolata
font_size: 11
background_color: '#f5f5f5'
# code is used for source code blocks
code:
font_color: $base_font_color
font_family: $literal_font_family
font_size: ceil($base_font_size)
padding: $code_font_size
line_height: 1.25
background_color: '#f5f5f5'
border_color: '#cccccc'
border_radius: $base_border_radius
border_width: 0.75
# headings
heading:
font_color: '#d9411e'
font_family: $base_font_family
font_style: bold
# h1 is used for part titles; equivalent to 22pt due to rounding
h1_font_size: floor($base_font_size * 2.1)
# h2 is used for chapter titles; equivalent to 20pt due to rounding
h2_font_size: floor($base_font_size * 1.9)
# equivalent to 16pt due to rounding
h3_font_size: ceil($base_font_size * 1.53)
# equivalent to 13.125pt
h4_font_size: $base_font_size_large
# equivalent to 10.5pt
h5_font_size: $base_font_size
#equivalent to 8.925pt
h6_font_size: $base_font_size_small
line_height: 1.2
margin_top: $vertical_rhythm * 0.2
margin_bottom: $vertical_rhythm * 0.8
padding: [0, 0, 5, 0]
# Applies only to the title page
title_page:
align: right
logo:
top: 10%
image: image:../../images/Solr_Logo_on_white.png[pdfwidth=50%]
align: left
title:
top: 55%
font_size: $heading_h1_font_size
font_color: '#d9411e'
line_height: 0.9
subtitle:
font_size: $heading_h3_font_size
font_style: bold_italic
line_height: 1
authors:
margin_top: $base_font_size * 1.25
font_size: $base_font_size
revision:
margin_top: $base_font_size * 1.25
block:
margin_top: 0
margin_bottom: $vertical_rhythm
caption:
align: left
font:
style: italic
color: 7a2518
margin_inside: $vertical_rhythm / 3
margin_outside: 0
lead:
font_size: $base_font_size_large
line_height: 1.4
abstract:
font_color: '#5c6266'
font_size: $lead_font_size
line_height: $lead_line_height
font_style: italic
admonition:
border_color: $base_border_color
border_width: $base_border_width
padding: [0, $horizontal_rhythm, 0, $horizontal_rhythm]
icon:
tip:
name: fa-lightbulb-o
stroke_color: '#428b30'
note:
name: fa-info-circle
stroke_color: '#19407c'
warning:
name: fa-exclamation-triangle
stroke_color: '#bf0000'
caution:
name: fa-fire
stroke_color: '#bf6900'
important:
name: fa-bolt
stroke_color: '#eeea74'
blockquote:
font_color: $base_font_color
font_size: $base_font_size
font_style: italic
border_color: $base_border_color
border_width: 5
padding: [$vertical_rhythm / 2, $horizontal_rhythm, $vertical_rhythm / -2, $horizontal_rhythm + $blockquote_border_width / 2]
cite_font_size: $base_font_size_small
cite_font_color: '#999999'
#conums are used for inline callouts
conum:
font_family: M+1mn Fallback
font_color: $literal_font_color
font_size: $base_font_size_large
line_height: 4 / 3
example:
border_color: $base_border_color
border_radius: $base_border_radius
border_width: 0.75
background_color: transparent
padding: [$vertical_rhythm, $horizontal_rhythm, 0, $horizontal_rhythm]
image:
align: left
border_color: $base_border_color
border_radius: $base_border_radius
border_width: 0.75
prose:
margin_top: 0
margin_bottom: $vertical_rhythm
sidebar:
border_color: $page_background_color
border_radius: $base_border_radius
border_width: $base_border_width
background_color: '#eeeeee'
padding: [$vertical_rhythm, $vertical_rhythm * 1.25, 0, $vertical_rhythm * 1.25]
title:
align: center
font_color: $heading_font_color
font_family: $heading_font_family
font_size: $heading_h4_font_size
font_style: $heading_font_style
thematic_break:
border_color: $base_border_color
border_style: solid
border_width: $base_border_width
margin_top: $vertical_rhythm * 0.5
margin_bottom: $vertical_rhythm * 1.5
description_list:
term_font_style: bold
term_spacing: $vertical_rhythm / 4
description_indent: $horizontal_rhythm * 1.25
outline_list:
indent: $horizontal_rhythm * 1.5
# NOTE item_spacing applies to list items that do not have complex content
item_spacing: $vertical_rhythm / 2
table:
background_color: $page_background_color
head_background_color: '#e6e7e8'
#head_font_color: $base_font_color
head_font_style: bold
even_row_background_color: '#f9f9f9'
#odd_row_background_color: <hex value>
foot_background_color: '#f0f0f0'
border_color: '#dddddd'
border_width: $base_border_width
cell_padding: [3, 3, 6, 3]
toc:
dot_leader_color: '#dddddd'
#dot_leader_content: '. '
indent: $horizontal_rhythm
line_height: 1.4
header:
font:
size: $base_font_size
color: $base_font_color
style: bold_italic
height: $base_line_height_length * 2.5
recto_content:
left: 'Apache Solr Reference Guide {solr-docs-version}'
right: 'Page {page-number} of {page-count}'
verso_content:
left: 'Page {page-number} of {page-count}'
right: 'Apache Solr Reference Guide {solr-docs-version}'
footer:
font_size: $base_font_size_small
font_color: $base_font_color
# NOTE if background_color is set, background and border will span width of page
border_color: '#dddddd'
border_width: 0.25
height: $base_line_height_length * 2.5
line_height: 1
padding: [$base_line_height_length / 2, 1, 0, 1]
vertical_align: top
#image_vertical_align: <alignment> or <number>
# additional attributes for content:
# * {page-count}
# * {page-number}
# * {document-title}
# * {document-subtitle}
# * {chapter-title}
# * {section-title}
# * {section-or-chapter-title}
# We have added some custom variables from the build, see _config.yml.template
recto_content:
right: 'Guide Version {solr-guide-version} - Published: {build-date}'
left: '(C) {build-year}, Apache Software Foundation'
verso_content:
left: 'Guide Version {solr-guide-version} - Published: {build-date}'
right: '(C) {build-year}, Apache Software Foundation'
colophon:
font_size: $base_font_size_small

50
solr/solr-ref-guide/tools/BuildNavAndPDFBody.java → solr/solr-ref-guide/tools/BuildNavDataFiles.java
View File

@ -28,7 +28,7 @@ import org.asciidoctor.Asciidoctor;
import org.asciidoctor.ast.DocumentHeader;
public class BuildNavAndPDFBody {
public class BuildNavDataFiles {
public static void main(String[] args) throws Exception {
if (args.length != 2) {
@ -83,53 +83,23 @@ public class BuildNavAndPDFBody {
}
}
// Build up the PDF file,
// while doing this also build up some next/prev maps for use in building the scrollnav
File pdfFile = new File(new File(adocDir, "_data"), "pdf-main-body.adoc");
if (pdfFile.exists()) {
throw new RuntimeException(pdfFile.toString() + " already exists");
}
// Loop over all files "in order" to build up next/prev maps for use in building the scrollnav
final Map<String,Page> nextPage = new HashMap<String,Page>();
final Map<String,Page> prevPage = new HashMap<String,Page>();
System.out.println("Creating " + pdfFile.toString());
try (Writer w = new OutputStreamWriter(new FileOutputStream(pdfFile), "UTF-8")) {
// Note: not worrying about headers or anything like that ...
// expecting this file to just be included by the main PDF file.
System.out.println("Looping over pages to build nav data");
// track how deep we are so we can adjust headers accordingly
// start with a "negative" depth to treat all "top level" pages as same depth as main-page using Math.max
// (see below)
final AtomicInteger depth = new AtomicInteger(-1);
// the previous page seen in our walk
{ // the previous page seen during our walk
AtomicReference<Page> previous = new AtomicReference<Page>();
mainPage.depthFirstWalk(new Page.RecursiveAction() {
public boolean act(Page page) {
try {
if (null != previous.get()) {
// add previous as our 'prev' page, and ourselves as the 'next' of previous
prevPage.put(page.shortname, previous.get());
nextPage.put(previous.get().shortname, page);
}
previous.set(page);
// use an explicit anchor, since the auto-generated ID from the "title" might not match
// the shortname/filename
w.append("[[").append(page.shortname).append("]]\n");
// HACK: where this file actually lives will determine what we need here...
w.write("include::../");
w.write(page.file.getName());
w.write("[leveloffset=+"+Math.max(0, depth.intValue())+"]\n\n");
depth.incrementAndGet();
return true;
} catch (IOException ioe) {
throw new RuntimeException("IOE recursively acting on " + page.shortname, ioe);
if (null != previous.get()) {
// add previous as our 'prev' page, and ourselves as the 'next' of previous
prevPage.put(page.shortname, previous.get());
nextPage.put(previous.get().shortname, page);
}
}
public void postKids(Page page) {
depth.decrementAndGet();
previous.set(page);
return true;
}
});
}

62
solr/solr-ref-guide/tools/CheckLinksAndAnchors.java
View File

@ -57,13 +57,10 @@ import org.jsoup.select.NodeVisitor;
*
* <ul>
* <li>
* Asciidoctor doesn't do a good job of rectifying situations where multiple documents are included in one
* massive (PDF) document may have identical anchors (either explicitly defined, or implicitly defined because of
* section headings). Asciidoctor also doesn't support linking directly to another (included) asciidoc
* document by name, unless there is an explicit '#fragement' used in the link.
* Validates that no file contains the same anchor more then once.
* </li>
* <li>
* Any "relative" link should point to a file that actually exists.
* Validates that relative links point to a file that actually exists, and if it's part of the ref-guide that the '#fragement' in the link refers to an ID that exists in that file.
* </li>
* <li>
* Our use of "<a href="https://getbootstrap.com/">Bootstrap</a>" features leverage some custom javascript
@ -75,8 +72,7 @@ import org.jsoup.select.NodeVisitor;
*
* <p>
* This tool parses the generated HTML site, looking for these situations in order to fail the build, since
* (depending on the type of check) these situations will result in inconsistent/broken HTML, or equivalent
* problems in the generated PDF.
* (depending on the type of check) these situations will result in inconsistent/broken HTML.
* </p>
* <p>
* This tool supports 2 command line options:
@ -158,12 +154,12 @@ public class CheckLinksAndAnchors { // TODO: rename this class now that it does
System.exit(-1);
}
final Map<String,List<File>> idsToFiles = new HashMap<>();
final Map<File,List<URI>> filesToRelativeLinks = new HashMap<>();
final Set<String> idsInMultiFiles = new LinkedHashSet<>(0);
final Map<String,Set<String>> filesToIds = new HashMap<>();
int totalLinks = 0;
int totalRelativeLinks = 0;
int totalIds = 0;
for (File file : pages) {
//System.out.println("input File URI: " + file.toURI().toString());
@ -171,6 +167,11 @@ public class CheckLinksAndAnchors { // TODO: rename this class now that it does
assert ! filesToRelativeLinks.containsKey(file);
final List<URI> linksInThisFile = new ArrayList<URI>(17);
filesToRelativeLinks.put(file, linksInThisFile);
final Set<String> idsInThisFile = new LinkedHashSet<String>(17);
filesToIds.put(file.getName(), idsInThisFile);
// use this for error reporting if an ID exists multiple times in a single document
final Map<String,List<Element>> idsToNodes = new HashMap<>();
final String fileContents = readFile(file.getPath());
final Document doc = Jsoup.parse(fileContents);
@ -183,13 +184,11 @@ public class CheckLinksAndAnchors { // TODO: rename this class now that it does
throw new RuntimeException(file.getName() + " has no main content: " + mainContentSelector);
}
// Add all of the IDs in (the content of) this doc to idsToFiles (and idsInMultiFiles if needed)
// All of the ID (nodes) in (the content of) this doc
final Elements nodesWithIds = mainContent.select("[id]");
if (bareBones) {
// It's a pain in the ass to customize the HTML output structure asciidoctor's bare-bones html5 backend
// so instead we "fake" that the body tag contains the attribute we use in jekyll
// (and what gets added explicitly to each top level section in the PDF)
nodesWithIds.add(new Element(Tag.valueOf("body"), "").attr("id", file.getName().replaceAll("\\.html$","")));
} else {
// We have to add Jekyll's <body> to the nodesWithIds so we check the main section anchor as well
@ -213,16 +212,16 @@ public class CheckLinksAndAnchors { // TODO: rename this class now that it does
" contains 'preamble' anchor, this is special in jekyll and must not be used in content.");
} else {
foundPreamble = true;
continue;
continue; // Note: we specifically don't count this in totalIds
}
}
if (idsToFiles.containsKey(id)) {
idsInMultiFiles.add(id);
} else {
idsToFiles.put(id, new ArrayList<File>(1));
if (idsInThisFile.contains(id)) {
problems++;
System.err.println(file.toURI().toString() + " contains ID multiple times: " + id);
}
idsToFiles.get(id).add(file);
idsInThisFile.add(id);
totalIds++; // Note: we specifically don't count 'preamble'
}
// check for (relative) links that don't include a fragment
@ -271,15 +270,6 @@ public class CheckLinksAndAnchors { // TODO: rename this class now that it does
problems += validateHtmlStructure(file, mainContent);
}
// if there are problematic ids, report them
for (String id : idsInMultiFiles) {
problems++;
System.err.println("ID occurs multiple times: " + id);
for (File file : idsToFiles.get(id)) {
System.err.println(" ... " + file.toURI().toString());
}
}
// check every (realtive) link in every file to ensure the frag exists in the target page
for (Map.Entry<File,List<URI>> entry : filesToRelativeLinks.entrySet()) {
final File source = entry.getKey();
@ -296,16 +286,14 @@ public class CheckLinksAndAnchors { // TODO: rename this class now that it does
} else {
if ( ! path.startsWith("../") ) {
// if the dest file is part of the ref guide (ie: not an "up and out" link to javadocs)
// then we validate the fragment is known and unique...
// then we validate the fragment is known and exists in that file...
final String frag = link.getFragment();
if ( ! idsInMultiFiles.contains(frag) ) { // skip problematic dups already reported
if ( ( ! idsToFiles.containsKey(frag) ) || // no file contains this id, or...
// id exists, but not in linked file
( ! idsToFiles.get(frag).get(0).getName().equals(path) )) {
problems++;
System.err.println("Relative link points at id that doesn't exist in dest: " + link);
System.err.println(" ... source: " + source.toURI().toString());
}
final Set<String> knownIdsInDest = filesToIds.get(dest.getName());
assert null != knownIdsInDest : dest.getName();
if (! knownIdsInDest.contains(frag) ) {
problems++;
System.err.println("Relative link points at id that doesn't exist in dest: " + link);
System.err.println(" ... source: " + source.toURI().toString());
}
}
}
@ -313,7 +301,7 @@ public class CheckLinksAndAnchors { // TODO: rename this class now that it does
}
System.err.println("Processed " + totalLinks + " links (" + totalRelativeLinks + " relative) to " +
idsToFiles.size() + " anchors in " + pages.length + " files");
totalIds + " anchors in " + pages.length + " files");
if (0 < problems) {
System.err.println("Total of " + problems + " problems found");
System.exit(-1);

90
solr/solr-ref-guide/tools/ReducePDFSize.java
View File

@ -1,90 +0,0 @@
/*
* 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.
*/
import java.io.File;
import java.io.IOException;
import java.io.OutputStream;
import org.apache.pdfbox.cos.COSBase;
import org.apache.pdfbox.cos.COSName;
import org.apache.pdfbox.cos.COSObject;
import org.apache.pdfbox.cos.COSStream;
import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.pdmodel.common.PDStream;
/**
* A simple command line utility for reducing the size of the ref-guide PDF.
* <p>
* Currently this script focuses on using {@link COSName#FLATE_DECODE} to compress the (decoded) Objects
* in the source PDF, but other improvements may be possible in the future.
* </p>
* <p>
* This code is originally based on the <code>WriteDecodedDoc</code> example provided with <a href="https://pdfbox.apache.org/">Apache PDFBox</a>.
* </p>
* <p>
* <b>NOTE:</b> This class should <em>NOT</em> be considered a general purpose tool for reducing the size of
* <em>any</em> PDF.
* Decisions made in this code can and will be focused explicitly on serving the purpose of reducing the size of the
* Solr Reference Guide PDF, as originally produced by asciidoctor, and may not be generally useful for all PDFs
* "in the wild".
* </p>
*/
public class ReducePDFSize {
public static void main(String[] args) throws IOException {
if (2 != args.length) {
throw new RuntimeException("arg0 must be input file, org1 must be output file");
}
String in = args[0];
String out = args[1];
PDDocument doc = null;
try {
doc = PDDocument.load(new File(in));
doc.setAllSecurityToBeRemoved(true);
for (COSObject cosObject : doc.getDocument().getObjects()) {
COSBase base = cosObject.getObject();
// if it's a stream: decode it, then re-write it using FLATE_DECODE
if (base instanceof COSStream) {
COSStream stream = (COSStream) base;
byte[] bytes;
try {
bytes = new PDStream(stream).toByteArray();
} catch (IOException ex) {
// NOTE: original example code from PDFBox just logged & "continue;"d here, 'skipping' this stream.
// If this type of failure ever happens, we can (perhaps) consider (re)ignoring this type of failure?
//
// IIUC then that will leave the original (non-decoded / non-flated) stream in place?
throw new RuntimeException("can't serialize byte[] from: " +
cosObject.getObjectNumber() + " " +
cosObject.getGenerationNumber() + " obj: " +
ex.getMessage(), ex);
}
stream.removeItem(COSName.FILTER);
OutputStream streamOut = stream.createOutputStream(COSName.FLATE_DECODE);
streamOut.write(bytes);
streamOut.close();
}
}
doc.getDocumentCatalog();
doc.save( out );
} finally {
if ( doc != null ) {
doc.close();
}
}
}
}