summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--.gitignore1
-rw-r--r--doc/Makefile31
-rwxr-xr-xdoc/badges.py150
-rw-r--r--doc/source/conf.py2
4 files changed, 180 insertions, 4 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/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