diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | doc/Makefile | 31 | ||||
| -rwxr-xr-x | doc/badges.py | 150 | ||||
| -rw-r--r-- | doc/source/conf.py | 2 |
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 |