infra/tools/dockerbuild/markdown.py

# Copyright 2017 The Chromium Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

import os

import packaging.version

from . import util

# Default output path of generated Markdown document.
DEFAULT_PATH = os.path.join(util.PKG_DIR, 'wheels.md')


class Generator(object):
  _INFRA_GITILES_PATH = 'https://chromium.googlesource.com/infra/infra'
  _INFRA_DOCKERBUILD_PATH = 'infra/tools/dockerbuild'

  _HEADER = """\
# dockerbuild-generated wheel packages

This file is automatically generated by `dockerbuild`'s `wheel-dump` subcommand.
It was generated from the list [here](./wheel.py).

Please see [VPython and You] for a brief tutorial on how to use vpython.

If there's a wheel you need which is missing, please [file a bug][bug].

[bug]: https://bugs.chromium.org/p/chromium/issues/entry?template=+Vpython+Wheel+Request
[VPython and You]: https://chromium.googlesource.com/infra/infra/+/master/doc/users/vpython_one_page.md

[TOC]

# Wheel List

This list represents the current set of configured `dockerbuild` wheels in
[wheel.py](./wheel.py).

"""

  _WHEEL_NAME_TEMPLATE_23 = """\
## **%(name)s**

"""

  _WHEEL_NAME_TEMPLATE = """\
## **%(name)s-%(pyversion)s**

"""

  _WHEEL_TEMPLATE = """\
### %(version)s

```protobuf
wheel: <
  name: "%(package_name)s"
  version: "%(package_tag)s"
>
```

%(supported)s%(extra_data)s

"""

  _FOOTER = """\

# Contact

If a wheel is needed, but is not in this list, please
contact Chrome Operations:

* `luci-eng@google.com`
* [File a bug][bug]
"""

  def __init__(self):
    self._packages = {}

  def add_package(self, whl, plat):
    pyversions = tuple(whl.spec.pyversions or () if whl.spec.universal else ())
    key = (whl.spec.name, whl.spec.version, pyversions)
    _, v = self._packages.setdefault(key, (whl, set()))
    if plat:
      v.add(plat.name)

  def write(self, fd):
    fd.write(self._HEADER)

    categorized_packages = {}
    for (name, version, pyversions), (whl, plats) in self._packages.items():
      for pyversion in (pyversions or ('',)):
        key = (name, pyversion)
        categorized_packages.setdefault(key, {})[version] = (whl, plats)

    for (name, pyversion), versions in sorted(categorized_packages.items()):
      wheel_name_template = self._WHEEL_NAME_TEMPLATE_23
      if pyversion:
        wheel_name_template = self._WHEEL_NAME_TEMPLATE
      fd.write(wheel_name_template % dict(
          name=name,
          pyversion=pyversion,
      ))

      for version, (whl, plats) in sorted(
          versions.items(), key=lambda x: packaging.version.parse(x[0])):
        package = whl.cipd_package(templated=True)

        # Build an italic list of supported platforms.
        supported = '\n'.join([''] + [
            '* *%s*' % (plat_name,)
            for plat_name in sorted(plats) or ('universal',)
        ])

        fd.write(self._WHEEL_TEMPLATE % dict(
            version=whl.build_id,
            supported=supported,
            extra_data='\n'.join(whl.md_lines),
            package_name=package.name,
            package_tag=package.tags[0],
        ))

    fd.write(self._FOOTER)