Merge branch 'tristan/docs-version-badge' into 'master'

Release badges

See merge request BuildStream/buildstream!742

9 files changed, 252 insertions, 8 deletions

diff --git a/.gitignore b/.gitignore
index 04f9e1690..fae0f4eea 100644
--- a/.gitignore
+++ b/.gitignore
@@ -26,6 +26,7 @@ __pycache__/
 buildstream/__version__.py
 
 # Autogenerated doc
+doc/source/badges/
 doc/source/sessions/
 doc/source/elements/
 doc/source/sources/
diff --git a/README.rst b/README.rst
index f9a750052..f60ad8b1c 100644
--- a/README.rst
+++ b/README.rst
@@ -1,5 +1,12 @@
 About
 -----
+
+.. image:: https://buildstream.gitlab.io/buildstream/_static/release.svg
+   :target: https://gitlab.com/BuildStream/buildstream/commits/bst-1.2
+
+.. image:: https://buildstream.gitlab.io/buildstream/_static/snapshot.svg
+   :target: https://gitlab.com/BuildStream/buildstream/commits/master
+
 .. image:: https://gitlab.com/BuildStream/buildstream/badges/master/pipeline.svg
    :target: https://gitlab.com/BuildStream/buildstream/commits/master
 
diff --git a/doc/Makefile b/doc/Makefile
index 51d4513ce..f52b869ef 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -35,7 +35,7 @@ endif
 PYTHONPATH=$(CURDIR)/..:$(CURDIR)/../buildstream/plugins
 
 
-.PHONY: all clean templates templates-clean sessions sessions-prep sessions-clean html devhelp
+.PHONY: all clean templates templates-clean sessions sessions-prep sessions-clean badges badges-clean html devhelp
 
 # Canned recipe for generating plugin api skeletons
 #   $1 = the plugin directory
@@ -70,9 +70,13 @@ endef
 
 all: html devhelp
 
-clean: templates-clean sessions-clean
+clean: templates-clean sessions-clean badges-clean
 	rm -rf build
 
+############################################################
+#                 Plugin doc templates                     #
+############################################################
+
 # Generate rst templates for the docs using a mix of sphinx-apidoc and
 # our 'plugin-doc-skeleton' routine for plugin pages.
 templates:
@@ -86,6 +90,10 @@ templates-clean:
 	rm -rf source/elements
 	rm -rf source/sources
 
+############################################################
+#                   Session captures                       #
+############################################################
+
 # Stage the stored sessions into the place where they will
 # be used in the build.
 #
@@ -111,10 +119,27 @@ sessions: sessions-prep
 sessions-clean:
 	rm -rf source/sessions
 
+
+############################################################
+#                  Generate release badges                 #
+############################################################
+badges-clean:
+	rm -rf source/badges
+
+badges:
+	mkdir -p source/badges
+	$(CURDIR)/badges.py > source/badges/snapshot.svg
+	$(CURDIR)/badges.py --release > source/badges/release.svg
+
+
+############################################################
+#                    Main sphinx build                     #
+############################################################
+
 # Targets which generate docs with sphinx build
 #
 #
-html devhelp: templates sessions
+html devhelp: templates sessions badges
 	@echo "Building $@..."
 	PYTHONPATH=$(PYTHONPATH) \
 	    $(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) "$(BUILDDIR)/$@" \
diff --git a/doc/badges.py b/doc/badges.py
new file mode 100755
index 000000000..5e20dc7f9
--- /dev/null
+++ b/doc/badges.py
@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+#
+#  Copyright (C) 2018 Codethink Limited
+#
+#  This program is free software; you can redistribute it and/or
+#  modify it under the terms of the GNU Lesser General Public
+#  License as published by the Free Software Foundation; either
+#  version 2 of the License, or (at your option) any later version.
+#
+#  This library is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
+#  Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public
+#  License along with this library. If not, see <http://www.gnu.org/licenses/>.
+#
+#  Authors:
+#        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
+#
+import click
+import subprocess
+import re
+
+# The badge template is modeled after the gitlab badge svgs
+#
+BADGE_TEMPLATE = """
+<svg xmlns="http://www.w3.org/2000/svg"
+     xmlns:xlink="http://www.w3.org/1999/xlink"
+     width="116" height="20">
+  <a xlink:href="{url_target}">
+    <linearGradient id="{badge_name}_b" x2="0" y2="100%">
+      <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+      <stop offset="1" stop-opacity=".1"/>
+    </linearGradient>
+
+    <mask id="{badge_name}_a">
+      <rect width="116" height="20" rx="3" fill="#fff"/>
+    </mask>
+
+    <g mask="url(#{badge_name}_a)">
+      <path fill="#555"
+            d="M0 0 h62 v20 H0 z"/>
+      <path fill="{color}"
+            d="M62 0 h54 v20 H62 z"/>
+      <path fill="url(#{badge_name}_b)"
+            d="M0 0 h116 v20 H0 z"/>
+    </g>
+
+    <g fill="#fff" text-anchor="middle">
+      <g font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="31" y="15" fill="#010101" fill-opacity=".3">
+          {badge_name}
+        </text>
+        <text x="31" y="14">
+          {badge_name}
+        </text>
+        <text x="89" y="15" fill="#010101" fill-opacity=".3">
+          {version}
+        </text>
+        <text x="89" y="14">
+          {version}
+        </text>
+      </g>
+    </g>
+  </a>
+</svg>
+"""
+
+URL_FORMAT = 'https://download.gnome.org/sources/BuildStream/{brief_version}/BuildStream-{full_version}.tar.xz'
+RELEASE_COLOR = '#0040FF'
+SNAPSHOT_COLOR = '#FF8000'
+VERSION_TAG_MATCH = r'([0-9]*)\.([0-9]*)\.([0-9]*)'
+
+
+# Parse a release tag and return a three tuple
+# of the major, minor and micro version.
+#
+# Tags which do not follow the release tag format
+# will just be returned as (0, 0, 0)
+#
+def parse_tag(tag):
+    match = re.search(VERSION_TAG_MATCH, tag)
+    if match:
+        major = match.group(1)
+        minor = match.group(2)
+        micro = match.group(3)
+        return (int(major), int(minor), int(micro))
+
+    return (0, 0, 0)
+
+
+# Call out to git and guess the latest version,
+# this will just return (0, 0, 0) in case of any error.
+#
+def guess_version(release):
+    try:
+        tags_output = subprocess.check_output(['git', 'tag'])
+    except CalledProcessError:
+        return (0, 0, 0)
+
+    # Parse the `git tag` output into a list of integer tuples
+    tags_output = tags_output.decode('UTF-8')
+    all_tags = tags_output.splitlines()
+    all_versions = [parse_tag(tag) for tag in all_tags]
+
+    # Filter the list by the minor point version, if
+    # we are checking for the latest "release" version, then
+    # only pickup even number minor points.
+    #
+    filtered_versions = [
+        version for version in all_versions
+        if (version[1] % 2) == (not release)
+    ]
+
+    # Make sure they are sorted, and take the last one
+    sorted_versions = sorted(filtered_versions)
+    latest_version = sorted_versions[-1]
+
+    return latest_version
+
+
+@click.command(short_help="Generate the version badges")
+@click.option('--release', is_flag=True, default=False,
+              help="Whether to generate the badge for the release version")
+def generate_badges(release):
+    """Generate the version badge svg files
+    """
+    major, minor, micro = guess_version(release)
+
+    if release:
+        badge_name = 'release'
+        color = RELEASE_COLOR
+    else:
+        badge_name = 'snapshot'
+        color = SNAPSHOT_COLOR
+
+    brief_version = '{major}.{minor}'.format(major=major, minor=minor)
+    full_version = '{major}.{minor}.{micro}'.format(major=major, minor=minor, micro=micro)
+    url_target = URL_FORMAT.format(brief_version=brief_version, full_version=full_version)
+    badge = BADGE_TEMPLATE.format(badge_name=badge_name,
+                                  version=full_version,
+                                  color=color,
+                                  url_target=url_target)
+    click.echo(badge, nl=False)
+    return 0
+
+
+if __name__ == '__main__':
+    generate_badges()
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 60477bbd5..5aaaed280 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -160,7 +160,7 @@ html_theme = 'sphinx_rtd_theme'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
+html_static_path = ['badges']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
diff --git a/doc/source/install_versions.rst b/doc/source/install_versions.rst
index a82cb9dc7..db0e35d76 100644
--- a/doc/source/install_versions.rst
+++ b/doc/source/install_versions.rst
@@ -13,8 +13,12 @@ For example, for a given version number ``X.Y.Z``
  * The ``X.<odd number>.*`` versions are development spanshots intended for testing.
 
 If you are :ref:`installing from git <install_git_checkout>`, please look for the latest
-tag in the latest release branch to ensure you're getting the latest release.
+tag to ensure you're getting the latest release.
 
-Current release branches:
- * `bst-1.2 (latest) <https://gitlab.com/BuildStream/buildstream/commits/bst-1.2>`_
- * `bst-1.0 (deprecated) <https://gitlab.com/BuildStream/buildstream/commits/bst-1.0>`_
+* Latest release:
+
+  .. include:: release-badge.rst
+
+* Latest development snapshot:
+
+  .. include:: snapshot-badge.rst
diff --git a/doc/source/main_install.rst b/doc/source/main_install.rst
index 80fe497ae..8890fb2cc 100644
--- a/doc/source/main_install.rst
+++ b/doc/source/main_install.rst
@@ -4,6 +4,11 @@
 
 Install
 =======
+
+.. include:: release-badge.rst
+
+.. include:: snapshot-badge.rst
+
 This section provides instructions for installing BuildStream and its
 companion artifact server on various platforms, along with any installation
 related materials.
diff --git a/doc/source/release-badge.rst b/doc/source/release-badge.rst
new file mode 100644
index 000000000..3a09b7f9f
--- /dev/null
+++ b/doc/source/release-badge.rst
@@ -0,0 +1,26 @@
+
+.. Use this file to include the badge in the documentation, but not in
+   the README.rst or gitlab rendered materials, that doesnt work.
+
+   This is partly a workaround for a sphinx issue, we will be able
+   to avoid the raw html once this is implemented in sphinx:
+
+       https://github.com/sphinx-doc/sphinx/issues/2240
+
+   Using the <object> tag instead of the <img> tag which sphinx generates
+   allows the svg to be "interactive", for us this basically means that
+   the link we encode in the badge svg is used, rather than static urls
+   which need to be used around the <img> tag.
+
+   WARNING: The custom CSS on the style tag will need to change if we
+            change the theme, so that the <object> tag behaves similar
+	    to how the <img> tag is themed by the style sheets.
+
+.. raw:: html
+
+   <a class="reference external image-reference">
+     <object style="margin-bottom:24px;vertical-align:middle"
+             data="https://buildstream.gitlab.io/buildstream/_static/release.svg"
+	     type="image/svg+xml"/>
+     </object>
+   </a>
diff --git a/doc/source/snapshot-badge.rst b/doc/source/snapshot-badge.rst
new file mode 100644
index 000000000..b4a3fc9f1
--- /dev/null
+++ b/doc/source/snapshot-badge.rst
@@ -0,0 +1,26 @@
+
+.. Use this file to include the badge in the documentation, but not in
+   the README.rst or gitlab rendered materials, that doesnt work.
+
+   This is partly a workaround for a sphinx issue, we will be able
+   to avoid the raw html once this is implemented in sphinx:
+
+       https://github.com/sphinx-doc/sphinx/issues/2240
+
+   Using the <object> tag instead of the <img> tag which sphinx generates
+   allows the svg to be "interactive", for us this basically means that
+   the link we encode in the badge svg is used, rather than static urls
+   which need to be used around the <img> tag.
+
+   WARNING: The custom CSS on the style tag will need to change if we
+            change the theme, so that the <object> tag behaves similar
+	    to how the <img> tag is themed by the style sheets.
+
+.. raw:: html
+
+   <a class="reference external image-reference">
+     <object style="margin-bottom:24px;vertical-align:middle"
+             data="https://buildstream.gitlab.io/buildstream/_static/snapshot.svg"
+	     type="image/svg+xml"/>
+     </object>
+   </a>