[Notes] [Git][BuildStream/buildstream][master] 4 commits: doc: Adding badges.py release badge generator



Title: GitLab

Tristan Van Berkom pushed to branch master at BuildStream / buildstream

Commits:

9 changed files:

Changes:

  • .gitignore
    ... ... @@ -26,6 +26,7 @@ __pycache__/
    26 26
     buildstream/__version__.py
    
    27 27
     
    
    28 28
     # Autogenerated doc
    
    29
    +doc/source/badges/
    
    29 30
     doc/source/sessions/
    
    30 31
     doc/source/elements/
    
    31 32
     doc/source/sources/
    

  • README.rst
    1 1
     About
    
    2 2
     -----
    
    3
    +
    
    4
    +.. image:: https://buildstream.gitlab.io/buildstream/_static/release.svg
    
    5
    +   :target: https://gitlab.com/BuildStream/buildstream/commits/bst-1.2
    
    6
    +
    
    7
    +.. image:: https://buildstream.gitlab.io/buildstream/_static/snapshot.svg
    
    8
    +   :target: https://gitlab.com/BuildStream/buildstream/commits/master
    
    9
    +
    
    3 10
     .. image:: https://gitlab.com/BuildStream/buildstream/badges/master/pipeline.svg
    
    4 11
        :target: https://gitlab.com/BuildStream/buildstream/commits/master
    
    5 12
     
    

  • doc/Makefile
    ... ... @@ -35,7 +35,7 @@ endif
    35 35
     PYTHONPATH=$(CURDIR)/..:$(CURDIR)/../buildstream/plugins
    
    36 36
     
    
    37 37
     
    
    38
    -.PHONY: all clean templates templates-clean sessions sessions-prep sessions-clean html devhelp
    
    38
    +.PHONY: all clean templates templates-clean sessions sessions-prep sessions-clean badges badges-clean html devhelp
    
    39 39
     
    
    40 40
     # Canned recipe for generating plugin api skeletons
    
    41 41
     #   $1 = the plugin directory
    
    ... ... @@ -70,9 +70,13 @@ endef
    70 70
     
    
    71 71
     all: html devhelp
    
    72 72
     
    
    73
    -clean: templates-clean sessions-clean
    
    73
    +clean: templates-clean sessions-clean badges-clean
    
    74 74
     	rm -rf build
    
    75 75
     
    
    76
    +############################################################
    
    77
    +#                 Plugin doc templates                     #
    
    78
    +############################################################
    
    79
    +
    
    76 80
     # Generate rst templates for the docs using a mix of sphinx-apidoc and
    
    77 81
     # our 'plugin-doc-skeleton' routine for plugin pages.
    
    78 82
     templates:
    
    ... ... @@ -86,6 +90,10 @@ templates-clean:
    86 90
     	rm -rf source/elements
    
    87 91
     	rm -rf source/sources
    
    88 92
     
    
    93
    +############################################################
    
    94
    +#                   Session captures                       #
    
    95
    +############################################################
    
    96
    +
    
    89 97
     # Stage the stored sessions into the place where they will
    
    90 98
     # be used in the build.
    
    91 99
     #
    
    ... ... @@ -111,10 +119,27 @@ sessions: sessions-prep
    111 119
     sessions-clean:
    
    112 120
     	rm -rf source/sessions
    
    113 121
     
    
    122
    +
    
    123
    +############################################################
    
    124
    +#                  Generate release badges                 #
    
    125
    +############################################################
    
    126
    +badges-clean:
    
    127
    +	rm -rf source/badges
    
    128
    +
    
    129
    +badges:
    
    130
    +	mkdir -p source/badges
    
    131
    +	$(CURDIR)/badges.py > source/badges/snapshot.svg
    
    132
    +	$(CURDIR)/badges.py --release > source/badges/release.svg
    
    133
    +
    
    134
    +
    
    135
    +############################################################
    
    136
    +#                    Main sphinx build                     #
    
    137
    +############################################################
    
    138
    +
    
    114 139
     # Targets which generate docs with sphinx build
    
    115 140
     #
    
    116 141
     #
    
    117
    -html devhelp: templates sessions
    
    142
    +html devhelp: templates sessions badges
    
    118 143
     	@echo "Building $@..."
    
    119 144
     	PYTHONPATH=$(PYTHONPATH) \
    
    120 145
     	    $(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) "$(BUILDDIR)/$@" \
    

  • doc/badges.py
    1
    +#!/usr/bin/env python3
    
    2
    +#
    
    3
    +#  Copyright (C) 2018 Codethink Limited
    
    4
    +#
    
    5
    +#  This program is free software; you can redistribute it and/or
    
    6
    +#  modify it under the terms of the GNU Lesser General Public
    
    7
    +#  License as published by the Free Software Foundation; either
    
    8
    +#  version 2 of the License, or (at your option) any later version.
    
    9
    +#
    
    10
    +#  This library is distributed in the hope that it will be useful,
    
    11
    +#  but WITHOUT ANY WARRANTY; without even the implied warranty of
    
    12
    +#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
    
    13
    +#  Lesser General Public License for more details.
    
    14
    +#
    
    15
    +#  You should have received a copy of the GNU Lesser General Public
    
    16
    +#  License along with this library. If not, see <http://www.gnu.org/licenses/>.
    
    17
    +#
    
    18
    +#  Authors:
    
    19
    +#        Tristan Van Berkom <tristan vanberkom codethink co uk>
    
    20
    +#
    
    21
    +import click
    
    22
    +import subprocess
    
    23
    +import re
    
    24
    +
    
    25
    +# The badge template is modeled after the gitlab badge svgs
    
    26
    +#
    
    27
    +BADGE_TEMPLATE = """
    
    28
    +<svg xmlns="http://www.w3.org/2000/svg"
    
    29
    +     xmlns:xlink="http://www.w3.org/1999/xlink"
    
    30
    +     width="116" height="20">
    
    31
    +  <a xlink:href="">
    
    32
    +    <linearGradient id="{badge_name}_b" x2="0" y2="100%">
    
    33
    +      <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
    
    34
    +      <stop offset="1" stop-opacity=".1"/>
    
    35
    +    </linearGradient>
    
    36
    +
    
    37
    +    <mask id="{badge_name}_a">
    
    38
    +      <rect width="116" height="20" rx="3" fill="#fff"/>
    
    39
    +    </mask>
    
    40
    +
    
    41
    +    <g mask="url(#{badge_name}_a)">
    
    42
    +      <path fill="#555"
    
    43
    +            d="M0 0 h62 v20 H0 z"/>
    
    44
    +      <path fill="{color}"
    
    45
    +            d="M62 0 h54 v20 H62 z"/>
    
    46
    +      <path fill="url(#{badge_name}_b)"
    
    47
    +            d="M0 0 h116 v20 H0 z"/>
    
    48
    +    </g>
    
    49
    +
    
    50
    +    <g fill="#fff" text-anchor="middle">
    
    51
    +      <g font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
    
    52
    +        <text x="31" y="15" fill="#010101" fill-opacity=".3">
    
    53
    +          {badge_name}
    
    54
    +        </text>
    
    55
    +        <text x="31" y="14">
    
    56
    +          {badge_name}
    
    57
    +        </text>
    
    58
    +        <text x="89" y="15" fill="#010101" fill-opacity=".3">
    
    59
    +          {version}
    
    60
    +        </text>
    
    61
    +        <text x="89" y="14">
    
    62
    +          {version}
    
    63
    +        </text>
    
    64
    +      </g>
    
    65
    +    </g>
    
    66
    +  </a>
    
    67
    +</svg>
    
    68
    +"""
    
    69
    +
    
    70
    +URL_FORMAT = 'https://download.gnome.org/sources/BuildStream/{brief_version}/BuildStream-{full_version}.tar.xz'
    
    71
    +RELEASE_COLOR = '#0040FF'
    
    72
    +SNAPSHOT_COLOR = '#FF8000'
    
    73
    +VERSION_TAG_MATCH = r'([0-9]*)\.([0-9]*)\.([0-9]*)'
    
    74
    +
    
    75
    +
    
    76
    +# Parse a release tag and return a three tuple
    
    77
    +# of the major, minor and micro version.
    
    78
    +#
    
    79
    +# Tags which do not follow the release tag format
    
    80
    +# will just be returned as (0, 0, 0)
    
    81
    +#
    
    82
    +def parse_tag(tag):
    
    83
    +    match = re.search(VERSION_TAG_MATCH, tag)
    
    84
    +    if match:
    
    85
    +        major = match.group(1)
    
    86
    +        minor = match.group(2)
    
    87
    +        micro = match.group(3)
    
    88
    +        return (int(major), int(minor), int(micro))
    
    89
    +
    
    90
    +    return (0, 0, 0)
    
    91
    +
    
    92
    +
    
    93
    +# Call out to git and guess the latest version,
    
    94
    +# this will just return (0, 0, 0) in case of any error.
    
    95
    +#
    
    96
    +def guess_version(release):
    
    97
    +    try:
    
    98
    +        tags_output = subprocess.check_output(['git', 'tag'])
    
    99
    +    except CalledProcessError:
    
    100
    +        return (0, 0, 0)
    
    101
    +
    
    102
    +    # Parse the `git tag` output into a list of integer tuples
    
    103
    +    tags_output = tags_output.decode('UTF-8')
    
    104
    +    all_tags = tags_output.splitlines()
    
    105
    +    all_versions = [parse_tag(tag) for tag in all_tags]
    
    106
    +
    
    107
    +    # Filter the list by the minor point version, if
    
    108
    +    # we are checking for the latest "release" version, then
    
    109
    +    # only pickup even number minor points.
    
    110
    +    #
    
    111
    +    filtered_versions = [
    
    112
    +        version for version in all_versions
    
    113
    +        if (version[1] % 2) == (not release)
    
    114
    +    ]
    
    115
    +
    
    116
    +    # Make sure they are sorted, and take the last one
    
    117
    +    sorted_versions = sorted(filtered_versions)
    
    118
    +    latest_version = sorted_versions[-1]
    
    119
    +
    
    120
    +    return latest_version
    
    121
    +
    
    122
    +
    
    123
    +@click.command(short_help="Generate the version badges")
    
    124
    +@click.option('--release', is_flag=True, default=False,
    
    125
    +              help="Whether to generate the badge for the release version")
    
    126
    +def generate_badges(release):
    
    127
    +    """Generate the version badge svg files
    
    128
    +    """
    
    129
    +    major, minor, micro = guess_version(release)
    
    130
    +
    
    131
    +    if release:
    
    132
    +        badge_name = 'release'
    
    133
    +        color = RELEASE_COLOR
    
    134
    +    else:
    
    135
    +        badge_name = 'snapshot'
    
    136
    +        color = SNAPSHOT_COLOR
    
    137
    +
    
    138
    +    brief_version = '{major}.{minor}'.format(major=major, minor=minor)
    
    139
    +    full_version = '{major}.{minor}.{micro}'.format(major=major, minor=minor, micro=micro)
    
    140
    +    url_target = URL_FORMAT.format(brief_version=brief_version, full_version=full_version)
    
    141
    +    badge = BADGE_TEMPLATE.format(badge_name=badge_name,
    
    142
    +                                  version=full_version,
    
    143
    +                                  color=color,
    
    144
    +                                  url_target=url_target)
    
    145
    +    click.echo(badge, nl=False)
    
    146
    +    return 0
    
    147
    +
    
    148
    +
    
    149
    +if __name__ == '__main__':
    
    150
    +    generate_badges()

  • doc/source/conf.py
    ... ... @@ -160,7 +160,7 @@ html_theme = 'sphinx_rtd_theme'
    160 160
     # Add any paths that contain custom static files (such as style sheets) here,
    
    161 161
     # relative to this directory. They are copied after the builtin static files,
    
    162 162
     # so a file named "default.css" will overwrite the builtin "default.css".
    
    163
    -html_static_path = []
    
    163
    +html_static_path = ['badges']
    
    164 164
     
    
    165 165
     # Add any extra paths that contain custom files (such as robots.txt or
    
    166 166
     # .htaccess) here, relative to this directory. These files are copied
    

  • doc/source/install_versions.rst
    ... ... @@ -13,8 +13,12 @@ For example, for a given version number ``X.Y.Z``
    13 13
      * The ``X.<odd number>.*`` versions are development spanshots intended for testing.
    
    14 14
     
    
    15 15
     If you are :ref:`installing from git <install_git_checkout>`, please look for the latest
    
    16
    -tag in the latest release branch to ensure you're getting the latest release.
    
    16
    +tag to ensure you're getting the latest release.
    
    17 17
     
    
    18
    -Current release branches:
    
    19
    - * `bst-1.2 (latest) <https://gitlab.com/BuildStream/buildstream/commits/bst-1.2>`_
    
    20
    - * `bst-1.0 (deprecated) <https://gitlab.com/BuildStream/buildstream/commits/bst-1.0>`_
    18
    +* Latest release:
    
    19
    +
    
    20
    +  .. include:: release-badge.rst
    
    21
    +
    
    22
    +* Latest development snapshot:
    
    23
    +
    
    24
    +  .. include:: snapshot-badge.rst

  • doc/source/main_install.rst
    ... ... @@ -4,6 +4,11 @@
    4 4
     
    
    5 5
     Install
    
    6 6
     =======
    
    7
    +
    
    8
    +.. include:: release-badge.rst
    
    9
    +
    
    10
    +.. include:: snapshot-badge.rst
    
    11
    +
    
    7 12
     This section provides instructions for installing BuildStream and its
    
    8 13
     companion artifact server on various platforms, along with any installation
    
    9 14
     related materials.
    

  • doc/source/release-badge.rst
    1
    +
    
    2
    +.. Use this file to include the badge in the documentation, but not in
    
    3
    +   the README.rst or gitlab rendered materials, that doesnt work.
    
    4
    +
    
    5
    +   This is partly a workaround for a sphinx issue, we will be able
    
    6
    +   to avoid the raw html once this is implemented in sphinx:
    
    7
    +
    
    8
    +       https://github.com/sphinx-doc/sphinx/issues/2240
    
    9
    +
    
    10
    +   Using the <object> tag instead of the <img> tag which sphinx generates
    
    11
    +   allows the svg to be "interactive", for us this basically means that
    
    12
    +   the link we encode in the badge svg is used, rather than static urls
    
    13
    +   which need to be used around the <img> tag.
    
    14
    +
    
    15
    +   WARNING: The custom CSS on the style tag will need to change if we
    
    16
    +            change the theme, so that the <object> tag behaves similar
    
    17
    +	    to how the <img> tag is themed by the style sheets.
    
    18
    +
    
    19
    +.. raw:: html
    
    20
    +
    
    21
    +   <a class="reference external image-reference">
    
    22
    +     <object style="margin-bottom:24px;vertical-align:middle"
    
    23
    +             data=""
    
    24
    +	     type="image/svg+xml"/>
    
    25
    +     </object>
    
    26
    +   </a>

  • doc/source/snapshot-badge.rst
    1
    +
    
    2
    +.. Use this file to include the badge in the documentation, but not in
    
    3
    +   the README.rst or gitlab rendered materials, that doesnt work.
    
    4
    +
    
    5
    +   This is partly a workaround for a sphinx issue, we will be able
    
    6
    +   to avoid the raw html once this is implemented in sphinx:
    
    7
    +
    
    8
    +       https://github.com/sphinx-doc/sphinx/issues/2240
    
    9
    +
    
    10
    +   Using the <object> tag instead of the <img> tag which sphinx generates
    
    11
    +   allows the svg to be "interactive", for us this basically means that
    
    12
    +   the link we encode in the badge svg is used, rather than static urls
    
    13
    +   which need to be used around the <img> tag.
    
    14
    +
    
    15
    +   WARNING: The custom CSS on the style tag will need to change if we
    
    16
    +            change the theme, so that the <object> tag behaves similar
    
    17
    +	    to how the <img> tag is themed by the style sheets.
    
    18
    +
    
    19
    +.. raw:: html
    
    20
    +
    
    21
    +   <a class="reference external image-reference">
    
    22
    +     <object style="margin-bottom:24px;vertical-align:middle"
    
    23
    +             data=""
    
    24
    +	     type="image/svg+xml"/>
    
    25
    +     </object>
    
    26
    +   </a>



  • [Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]