You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by ho...@apache.org on 2017/05/12 18:18:39 UTC
[3/3] lucene-solr:branch_6_6: SOLR-10675: differentiate DRAFT builds
of the html/pdf ref-guides vs the official releases
SOLR-10675: differentiate DRAFT builds of the html/pdf ref-guides vs the official releases
(cherry picked from commit b552127ea36bd54f70014bab67738d3f156b505a)
Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/0c2330be
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/0c2330be
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/0c2330be
Branch: refs/heads/branch_6_6
Commit: 0c2330bea082a8936e60aa61fea0e7a1a54f2300
Parents: c8c2aab
Author: Chris Hostetter <ho...@apache.org>
Authored: Fri May 12 11:10:41 2017 -0700
Committer: Chris Hostetter <ho...@apache.org>
Committed: Fri May 12 11:14:31 2017 -0700
----------------------------------------------------------------------
solr/solr-ref-guide/build.xml | 40 +++++++++++++++++--
solr/solr-ref-guide/meta-docs/pdf.adoc | 10 ++---
solr/solr-ref-guide/meta-docs/publish.adoc | 18 ++++++---
solr/solr-ref-guide/src/_config.yml.template | 2 +
solr/solr-ref-guide/src/_includes/footer.html | 2 +-
solr/solr-ref-guide/src/_includes/head.html | 3 +-
solr/solr-ref-guide/src/_includes/sidebar.html | 8 +++-
solr/solr-ref-guide/src/_includes/topnav.html | 1 +
solr/solr-ref-guide/src/_layouts/default.html | 2 +-
solr/solr-ref-guide/src/css/customstyles.css | 14 +++++++
solr/solr-ref-guide/src/css/ref-guide.css | 4 ++
solr/solr-ref-guide/src/draft-background.png | Bin 0 -> 5391 bytes
.../src/pdf/themes/refguide-theme.yml | 4 +-
13 files changed, 88 insertions(+), 20 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/0c2330be/solr/solr-ref-guide/build.xml
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/build.xml b/solr/solr-ref-guide/build.xml
index a23bac85..74e6dee 100644
--- a/solr/solr-ref-guide/build.xml
+++ b/solr/solr-ref-guide/build.xml
@@ -20,10 +20,12 @@
<project name="solr-ref-guide" default="default" xmlns:asciidoctor="antlib:org.asciidoctor.ant" >
<import file="../common-build.xml"/>
-
<!-- properties to use in our docs -->
<loadresource property="solr-docs-version">
- <propertyresource name="version.base"/>
+ <!-- NOTE: this is specifically only the "major.minor", it does not include the ".bugfix"
+ This is because we (currently) only release the guide for minor versions.
+ -->
+ <propertyresource name="version"/>
<filterchain>
<tokenfilter>
<filetokenizer/>
@@ -32,6 +34,7 @@
</filterchain>
</loadresource>
<loadresource property="solr-docs-version-path">
+ <!-- NOTE: This is the ${solr-docs-version} as a path suitbale for linking to javadocs -->
<propertyresource name="solr-docs-version"/>
<filterchain>
<tokenfilter>
@@ -40,12 +43,41 @@
</tokenfilter>
</filterchain>
</loadresource>
+ <!-- NOTE: ${solr-guide-version} is the version of this ref-guide.
+
+ By default, we assume this is the same as ${solr-docs-version} with a "-DRAFT" suffix
+ When releasing, specify an explicit value of this property on the command line.
+
+ NOTE: the ${solr-guide-version} used *may* be different from the version of Solr the guide
+ covers if we decide to do a bug-fix release of the ref-guide
+
+ Examples: (assume branch_6_1 where version=6.1.SOMETHING)
+
+ Basic nightly/local build of the 6.1 guide...
+
+ => ant build-pdf
+
+ Official release build of the 6.1 guide...
+
+ => ant build-pdf -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)
+
+ => ant build-pdf -Dsolr-guide-version=6.1.1
+
+ -->
+ <property name="solr-guide-version" value="${solr-docs-version}-DRAFT" />
+ <condition property="solr-guide-draft-status" value="" else="DRAFT">
+ <matches pattern="^\d+\.\d+(|\.\d+)$" string="${solr-guide-version}" />
+ </condition>
+
<property name="solr-javadocs" value="https://lucene.apache.org/solr/${solr-docs-version-path}/" />
<property name="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-docs-version}.pdf" />
+ <property name="pdf-filename" value="apache-solr-ref-guide-${solr-guide-version}.pdf" />
<!-- ====== TOOLS FOR GENERATING/VALIDATING BITS OF THE SITE / PDF ======= -->
<property name="tools-jar-name" value="solr-ref-guide-tools.jar" />
@@ -157,6 +189,8 @@
<!-- 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
-->
+ <attribute key="solr-guide-draft-status" value="${solr-guide-draft-status}" />
+ <attribute key="solr-guide-version" value="${solr-guide-version}" />
<attribute key="solr-docs-version" value="${solr-docs-version}" />
<attribute key="solr-javadocs" value="${solr-javadocs}" />
<attribute key="lucene-javadocs" value="${lucene-javadocs}" />
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/0c2330be/solr/solr-ref-guide/meta-docs/pdf.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/meta-docs/pdf.adoc b/solr/solr-ref-guide/meta-docs/pdf.adoc
index 74921be..1520d5c 100644
--- a/solr/solr-ref-guide/meta-docs/pdf.adoc
+++ b/solr/solr-ref-guide/meta-docs/pdf.adoc
@@ -86,11 +86,7 @@ Our Ant target (`build-pdf`) uses the following settings:
<!-- 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
-->
- <attribute key="solr-docs-version" value="${solr-docs-version}" />
- <attribute key="solr-javadocs" value="${solr-javadocs}" />
- <attribute key="lucene-javadocs" value="${lucene-javadocs}" />
- <attribute key="build-date" value="${DSTAMP}" />
- <attribute key="build-year" value="${current.year}" />
+ <!-- ... -->
</asciidoctor:convert>
----
@@ -124,7 +120,9 @@ There are a lot of options here. Note that some include the `<attribute>` tag an
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-docs-version" value="${solr-docs-version}" />`:: Sets the version to the current release version.
+`<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.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/0c2330be/solr/solr-ref-guide/meta-docs/publish.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/meta-docs/publish.adoc b/solr/solr-ref-guide/meta-docs/publish.adoc
index 5a8fccb..a2a6d41 100644
--- a/solr/solr-ref-guide/meta-docs/publish.adoc
+++ b/solr/solr-ref-guide/meta-docs/publish.adoc
@@ -22,9 +22,14 @@ The build process generates the PDF, including the page hierarchy, and then runs
To build the PDF:
-. Run `ant build-pdf`
+. Run `ant build-pdf -Dsolr-guide-version=X.Y`
. The resulting PDF will be in `solr/build/solr-ref-guide`.
+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.
++
+
=== Prerequisites
* 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.
@@ -134,10 +139,13 @@ The steps to publish the Guide differ depending on if it is the first time the G
=== Building the HTML Version
-If you have the required dependencies on your local machine, you can build the HTML version with `ant build-site`. The dependencies are listed in `solr-ref-guide/README.adoc`.
+If you have the required dependencies on your local machine, you can build the HTML version with `ant build-site -Dsolr-guide-version=X.Y`. The dependencies are listed in `solr-ref-guide/README.adoc`.
+Tip::
++
//TODO update Jenkins link
-If you do not have the required dependencies, and don't choose to install them, you can download the files from the Jenkins (https://builds.apache.org/job/Solr-reference-guide-jira-SOLR-10290/lastSuccessfulBuild/artifact/solr/build/solr-ref-guide/html-site/[Solr Reference Guide job]).
+If you do not have the required dependencies, and don't choose to install them, you can download the files from the Jenkins (https://builds.apache.org/job/Solr-reference-guide-jira-SOLR-10290/lastSuccessfulBuild/artifact/solr/build/solr-ref-guide/html-site/[Solr Reference Guide job]). But these HTML pages will have the `DRAFT` status noted in them and will not be suitable for publishing.
++
=== Publish a New Guide
// 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.
@@ -151,7 +159,7 @@ svn co --depth=immediates https://svn.apache.org/repos/asf/lucene/cms/trunk/cont
+
* 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_Z >> extpaths.txt`
+. Add Guide branch dir: `echo solr/guide/X_Y >> extpaths.txt`
. Commit changes:
+
[source,bash]
@@ -159,7 +167,7 @@ svn commit -m "Update CMS production sync exceptions for X_Y_Z Guide" extpaths.t
==== 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:
+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:
[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
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/0c2330be/solr/solr-ref-guide/src/_config.yml.template
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/_config.yml.template b/solr/solr-ref-guide/src/_config.yml.template
index c1e9271..dd7173c 100755
--- a/solr/solr-ref-guide/src/_config.yml.template
+++ b/solr/solr-ref-guide/src/_config.yml.template
@@ -85,6 +85,8 @@ asciidoc: {}
# 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.
solr-attributes: &solr-attributes-ref
+ solr-guide-draft-status: "${solr-guide-draft-status}"
+ solr-guide-version: "${solr-guide-version}"
solr-docs-version: "${solr-docs-version}"
solr-javadocs: "${solr-javadocs}"
lucene-javadocs: "${lucene-javadocs}"
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/0c2330be/solr/solr-ref-guide/src/_includes/footer.html
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/_includes/footer.html b/solr/solr-ref-guide/src/_includes/footer.html
index c22f239..ab96ec7 100755
--- a/solr/solr-ref-guide/src/_includes/footer.html
+++ b/solr/solr-ref-guide/src/_includes/footer.html
@@ -2,7 +2,7 @@
<div class="row">
<div class="col-lg-12 footer">
©{{ site.solr-attributes.build-year }} {{site.company_name}}. All rights reserved. <br />
-{% if page.last_updated %}<p>Page last updated:</span> {{page.last_updated}}<br/>{% endif %} Site last generated: {{ site.solr-attributes.build-date }} <br />
+{% if page.last_updated %}<p>Page last updated:</span> {{page.last_updated}}<br/>{% endif %} Site Version: {{ site.solr-attributes.solr-guide-version }} <br />Site last generated: {{ site.solr-attributes.build-date }} <br />
<p><img src="{{ "solr-sunOnly-small.png" }}" alt="Apache Solr"/></p>
</div>
</div>
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/0c2330be/solr/solr-ref-guide/src/_includes/head.html
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/_includes/head.html b/solr/solr-ref-guide/src/_includes/head.html
index 03b0db8..4e66593 100755
--- a/solr/solr-ref-guide/src/_includes/head.html
+++ b/solr/solr-ref-guide/src/_includes/head.html
@@ -3,7 +3,8 @@
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="{% if page.description %}{{ page.description | strip_html | strip_newlines | truncate: 160 }}{% endif %}">
<meta name="keywords" content="{{page.tags}}{% if page.tags %}, {% endif %} {{page.keywords}}">
-<title>{{ page.title }} | {{ site.site_title }}</title>
+{% comment %}NOTE: explicitly using the GUIDE version here (not solr) {% endcomment %}
+<title>{{ page.title }} | {{ site.site_title }} {{ site.solr-attributes.solr-guide-version}}</title>
<link rel="stylesheet" type="text/css" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
<!--<link rel="stylesheet" type="text/css" href="css/bootstrap.min.css">-->
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/0c2330be/solr/solr-ref-guide/src/_includes/sidebar.html
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/_includes/sidebar.html b/solr/solr-ref-guide/src/_includes/sidebar.html
index 4b4124c..56be9bc 100755
--- a/solr/solr-ref-guide/src/_includes/sidebar.html
+++ b/solr/solr-ref-guide/src/_includes/sidebar.html
@@ -1,7 +1,13 @@
{% assign sidebar = site.data.sidebar %}
<ul id="mysidebar" class="nav">
- <li class="sidebarTitle">{{sidebar.title}} <!-- TODO: version from site.data --></li>
+ <li class="sidebarTitle">{{sidebar.title}}</li>
+ {% if "" != site.solr-attributes.solr-guide-draft-status %}
+ <li class="draft-notice">
+ This is an unofficial DRAFT of the Guide for {{ site.solr-attributes.solr-docs-version }}.
+ <a href="https://lucene.apache.org/solr/guide/">Official releases of this Guide are available from the Solr website</a>.
+ </li>
+ {% endif %}
{% for level1item in sidebar.kids %}
<li class="sb-level1">
<a href="{{level1item.url | remove: "/"}}">{{ level1item.title }}</a>
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/0c2330be/solr/solr-ref-guide/src/_includes/topnav.html
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/_includes/topnav.html b/solr/solr-ref-guide/src/_includes/topnav.html
index 677f850..7ed1f68 100755
--- a/solr/solr-ref-guide/src/_includes/topnav.html
+++ b/solr/solr-ref-guide/src/_includes/topnav.html
@@ -8,6 +8,7 @@
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
+ {% comment %} NOTE: Explicitly using *SOLR* version here (not guide){% endcomment %}
<a class="fa fa-home fa-lg navbar-brand" href="index.html"> <span class="projectTitle"> {{site.topnav_title}} {{ site.solr-attributes.solr-docs-version }}</span></a>
</div>
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/0c2330be/solr/solr-ref-guide/src/_layouts/default.html
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/_layouts/default.html b/solr/solr-ref-guide/src/_layouts/default.html
index aa4601f..357dacf 100755
--- a/solr/solr-ref-guide/src/_layouts/default.html
+++ b/solr/solr-ref-guide/src/_layouts/default.html
@@ -31,7 +31,7 @@
</script>
</head>
-<body id="{{ page.shortname }}">
+<body class="{{ site.solr-attributes.solr-guide-draft-status }}" id="{{ page.shortname }}">
{% include topnav.html %}
<!-- Page Content -->
<div class="container">
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/0c2330be/solr/solr-ref-guide/src/css/customstyles.css
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/css/customstyles.css b/solr/solr-ref-guide/src/css/customstyles.css
index 057cd86..4499a0f 100755
--- a/solr/solr-ref-guide/src/css/customstyles.css
+++ b/solr/solr-ref-guide/src/css/customstyles.css
@@ -211,6 +211,20 @@ background-color: #347DBE;
padding: 2px 10px;
background-color: #f1f1f1;
}
+.nav li.draft-notice {
+ /* we don't want the draft water mark to make this hard to notice */
+ background-color: rgb(255, 255, 255);
+}
+.nav li.draft-notice a, .nav li.draft-notice a:hover, .nav li.draft-notice a:active .nav li.draft-notice a:focus {
+ display: inline;
+ color: #2156a5;
+ text-decoration: underline;
+
+ position: inherit;
+ line-height: inherit;
+ padding: inherit;
+ background-color: inherit;
+}
.nav > li > a {
line-height: 20px;
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/0c2330be/solr/solr-ref-guide/src/css/ref-guide.css
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/css/ref-guide.css b/solr/solr-ref-guide/src/css/ref-guide.css
index 100266b..2087abf 100644
--- a/solr/solr-ref-guide/src/css/ref-guide.css
+++ b/solr/solr-ref-guide/src/css/ref-guide.css
@@ -76,6 +76,10 @@ body
margin: 0;
}
+body.DRAFT {
+ background-image: url("../draft-background.png");
+}
+
a
{
background: transparent;
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/0c2330be/solr/solr-ref-guide/src/draft-background.png
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/draft-background.png b/solr/solr-ref-guide/src/draft-background.png
new file mode 100644
index 0000000..b6aac82
Binary files /dev/null and b/solr/solr-ref-guide/src/draft-background.png differ
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/0c2330be/solr/solr-ref-guide/src/pdf/themes/refguide-theme.yml
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/pdf/themes/refguide-theme.yml b/solr/solr-ref-guide/src/pdf/themes/refguide-theme.yml
index 5e272ce..eb79885 100644
--- a/solr/solr-ref-guide/src/pdf/themes/refguide-theme.yml
+++ b/solr/solr-ref-guide/src/pdf/themes/refguide-theme.yml
@@ -250,10 +250,10 @@ footer:
# * {section-or-chapter-title}
# We have added some custom variables from the build, see _config.yml.template
recto_content:
- right: 'Published: {build-date}'
+ right: 'Guide Version {solr-guide-version} - Published: {build-date}'
left: '(C) {build-year}, Apache Software Foundation'
verso_content:
- left: 'Published: {build-date}'
+ left: 'Guide Version {solr-guide-version} - Published: {build-date}'
right: '(C) {build-year}, Apache Software Foundation'
colophon:
font_size: $base_font_size_small