docs/mkdocs/scripts/figures/release_timeline.py - third_party/json - Git at Google


            
            """Draws the release timeline of home/releases/index.md as an inline SVG into docs/images/.


            The releases and their dates come from the tables of that page (rows like `| [v3.11.2](v3.11.2.md) | 2022-08-12 | ...`),

            
            so after adding a release to the page, run `python3 scripts/figures/release_timeline.py` from docs/mkdocs and commit

            
            the regenerated docs/images/release_timeline.svg. The page includes the SVG text with

            
            `--8<-- "images/release_timeline.svg"`, so it follows the light/dark toggle (see the `nj-fig` rules in

            
            docs/css/brand.css and the `nj-int-*` rules in docs/css/fig-integration.css). Every marker has a <title> tooltip.

            
            The timeline also marks the first commit of the repository (FIRST_COMMIT) as a diamond. Rows without a date (the "Unreleased" row) are skipped; any other release row that cannot be parsed stops the script.

            
            """

            
            import datetime

            
            import re

            
            import sys

            
            from pathlib import Path


            DOCS = Path(__file__).resolve().parents[2] / "docs"

            
            OUT = Path(__file__).resolve().parents[2] / "docs" / "images"

            
            PAGE = DOCS / "home" / "releases" / "index.md"


            ROW = re.compile(r"^\|\s*\[v(\d+)\.(\d+)\.(\d+)\]\([^)]*\)\s*\|\s*([^|]*?)\s*\|")

            
            W, LEFT, RIGHT = 880, 24, 856

            
            LABEL_ROW, CHAR_W = 17, 7.0

            
            FIRST_COMMIT = datetime.date(2013, 7, 4)  # "- initial commit" of the repository


            def parse(markdown):

            
                releases = []

            
                for line in markdown.splitlines():

            
                    if not line.startswith("| [v"):

            
                        continue

            
                    m = ROW.match(line)

            
                    if not m:

            
                        sys.exit("cannot parse release row: " + line)

            
                    try:

            
                        date = datetime.date.fromisoformat(m.group(4))

            
                    except ValueError:

            
                        sys.exit("cannot parse date in row: " + line)

            
                    releases.append(((int(m.group(1)), int(m.group(2)), int(m.group(3))), date))

            
                if len(releases) < 2:

            
                    sys.exit("found fewer than two releases in " + str(PAGE))

            
                if len({v for v, _ in releases}) != len(releases):

            
                    sys.exit("duplicate release in " + str(PAGE))

            
                return sorted(releases, key=lambda r: (r[1], r[0]))


            def name(version):

            
                return "v%d.%d.%d" % version


            def draw(releases):

            
                first, last = FIRST_COMMIT, releases[-1][1]

            
                start, end = datetime.date(first.year, 1, 1), datetime.date(last.year + 1, 1, 1)

            
                span = (end - start).days


                def xof(date):

            
                    return LEFT + (RIGHT - LEFT) * (date - start).days / span


                # minor labels, placed greedily into the lowest free row above the axis

            
                rows_end, labels = [], []

            
                for version, date in [(None, FIRST_COMMIT)] + releases:

            
                    if version is not None and version[2] != 0:

            
                        continue

            
                    text = "first commit" if version is None else "%d.%d" % version[:2]

            
                    x, half = xof(date), len(text) * CHAR_W / 2 + 2

            
                    row = next((i for i, e in enumerate(rows_end) if e < x - half), None)

            
                    if row is None:

            
                        rows_end.append(0)

            
                        row = len(rows_end) - 1

            
                    rows_end[row] = x + half

            
                    labels.append((x, row, text))

            
                top = 14 + LABEL_ROW * len(rows_end)

            
                axis = top + 12

            
                height = axis + 70


                s = ['<svg class="nj-fig nj-fig--timeline" viewBox="0 0 %d %d" role="img" aria-labelledby="nj-int-tl-title" '

            
                     'xmlns="http://www.w3.org/2000/svg">' % (W, height)]

            
                minors = sum(1 for v, _ in releases if v[2] == 0)

            
                s.append('<title id="nj-int-tl-title">Timeline from the first commit (%s) and the %d releases from %s (%s) to %s '

            
                         '(%s): %d minor or major releases, drawn as filled dots with their version above the axis, and %d patch '

            
                         'releases, drawn as rings. The first commit is drawn as a diamond.</title>'

            
                         % (first.isoformat(), len(releases), name(releases[0][0]), releases[0][1].isoformat(),

            
                            name(releases[-1][0]), last.isoformat(), minors, len(releases) - minors))

            
                # year grid

            
                for year in range(start.year, end.year + 1):

            
                    x = xof(datetime.date(year, 1, 1))

            
                    s.append('<line class="nj-int-grid" x1="%.1f" y1="%d" x2="%.1f" y2="%d"/>' % (x, top - 4, x, axis + 8))

            
                    if year < end.year:

            
                        mid = xof(datetime.date(year, 7, 1))

            
                        s.append('<text class="nj-int-year" x="%.1f" y="%d">%d</text>' % (mid, axis + 24, year))

            
                s.append('<line class="nj-int-axis" x1="%d" y1="%d" x2="%d" y2="%d"/>' % (LEFT, axis, RIGHT, axis))

            
                # major version spans

            
                majors = {}

            
                for version, date in releases:

            
                    majors.setdefault(version[0], []).append(date)

            
                for major, dates in sorted(majors.items()):

            
                    x0, x1 = xof(min(dates)), xof(max(dates))

            
                    y = axis + 42

            
                    s.append('<path class="nj-int-axis" fill="none" d="M%.1f %d V%d H%.1f V%d"/>' % (x0, y - 5, y, x1, y - 5))

            
                    s.append('<text class="nj-int-major" x="%.1f" y="%d" text-anchor="%s">%d.x</text>'

            
                             % ((x0 + x1) / 2 if x1 - x0 > 30 else x0, y + 17, "middle" if x1 - x0 > 30 else "start", major))

            
                # leaders and labels

            
                for x, row, text in labels:

            
                    y = top - row * LABEL_ROW

            
                    s.append('<line class="nj-int-leader" x1="%.1f" y1="%d" x2="%.1f" y2="%d"/>' % (x, y + 3, x, axis - 7))

            
                    s.append('<text class="nj-int-label" x="%.1f" y="%d">%s</text>' % (x, y, text))

            
                # markers: the first commit, then one per date, patch rings first so that minor dots stay on top

            
                x = xof(FIRST_COMMIT)

            
                s.append('<g><title>First commit %s</title><circle class="nj-int-hit" cx="%.1f" cy="%d" r="9"/>'

            
                         '<path class="nj-int-minor" d="M%.1f %d l7 -7 l7 7 l-7 7z" transform="translate(-7 0)"/></g>'

            
                         % (FIRST_COMMIT.isoformat(), x, axis, x, axis))

            
                by_date = {}

            
                for version, date in releases:

            
                    by_date.setdefault(date, []).append(version)

            
                groups = sorted(by_date.items(), key=lambda g: any(v[2] == 0 for v in g[1]))

            
                for date, versions in groups:

            
                    minor = any(v[2] == 0 for v in versions)

            
                    x = xof(date)

            
                    tip = ", ".join(name(v) for v in sorted(versions)) + " released " + date.isoformat()

            
                    s.append('<g><title>%s</title><circle class="nj-int-hit" cx="%.1f" cy="%d" r="9"/>'

            
                             '<circle class="%s" cx="%.1f" cy="%d" r="%g"/></g>'

            
                             % (tip, x, axis, "nj-int-minor" if minor else "nj-int-patch", x, axis, 6 if minor else 3.5))

            
                s.append('</svg>')

            
                return "\n".join(s) + "\n"


            releases = parse(PAGE.read_text(encoding="utf-8"))

            
            (OUT / "release_timeline.svg").write_text(draw(releases), encoding="utf-8")

            
            print("wrote", OUT / "release_timeline.svg", "with", len(releases), "releases")
	"""Draws the release timeline of home/releases/index.md as an inline SVG into docs/images/.

	The releases and their dates come from the tables of that page (rows like `\| [v3.11.2](v3.11.2.md) \| 2022-08-12 \| ...`),
	so after adding a release to the page, run `python3 scripts/figures/release_timeline.py` from docs/mkdocs and commit
	the regenerated docs/images/release_timeline.svg. The page includes the SVG text with
	`--8<-- "images/release_timeline.svg"`, so it follows the light/dark toggle (see the `nj-fig` rules in
	docs/css/brand.css and the `nj-int-*` rules in docs/css/fig-integration.css). Every marker has a <title> tooltip.
	The timeline also marks the first commit of the repository (FIRST_COMMIT) as a diamond. Rows without a date (the "Unreleased" row) are skipped; any other release row that cannot be parsed stops the script.
	"""
	import datetime
	import re
	import sys
	from pathlib import Path

	DOCS = Path(__file__).resolve().parents[2] / "docs"
	OUT = Path(__file__).resolve().parents[2] / "docs" / "images"
	PAGE = DOCS / "home" / "releases" / "index.md"

	ROW = re.compile(r"^\\|\s\[v(\d+)\.(\d+)\.(\d+)\]\([^)]\)\s\\|\s([^\|]?)\s\\|")
	W, LEFT, RIGHT = 880, 24, 856
	LABEL_ROW, CHAR_W = 17, 7.0
	FIRST_COMMIT = datetime.date(2013, 7, 4) # "- initial commit" of the repository


	def parse(markdown):
	releases = []
	for line in markdown.splitlines():
	if not line.startswith("\| [v"):
	continue
	m = ROW.match(line)
	if not m:
	sys.exit("cannot parse release row: " + line)
	try:
	date = datetime.date.fromisoformat(m.group(4))
	except ValueError:
	sys.exit("cannot parse date in row: " + line)
	releases.append(((int(m.group(1)), int(m.group(2)), int(m.group(3))), date))
	if len(releases) < 2:
	sys.exit("found fewer than two releases in " + str(PAGE))
	if len({v for v, _ in releases}) != len(releases):
	sys.exit("duplicate release in " + str(PAGE))
	return sorted(releases, key=lambda r: (r[1], r[0]))


	def name(version):
	return "v%d.%d.%d" % version


	def draw(releases):
	first, last = FIRST_COMMIT, releases[-1][1]
	start, end = datetime.date(first.year, 1, 1), datetime.date(last.year + 1, 1, 1)
	span = (end - start).days

	def xof(date):
	return LEFT + (RIGHT - LEFT) * (date - start).days / span

	# minor labels, placed greedily into the lowest free row above the axis
	rows_end, labels = [], []
	for version, date in [(None, FIRST_COMMIT)] + releases:
	if version is not None and version[2] != 0:
	continue
	text = "first commit" if version is None else "%d.%d" % version[:2]
	x, half = xof(date), len(text) * CHAR_W / 2 + 2
	row = next((i for i, e in enumerate(rows_end) if e < x - half), None)
	if row is None:
	rows_end.append(0)
	row = len(rows_end) - 1
	rows_end[row] = x + half
	labels.append((x, row, text))
	top = 14 + LABEL_ROW * len(rows_end)
	axis = top + 12
	height = axis + 70

	s = ['<svg class="nj-fig nj-fig--timeline" viewBox="0 0 %d %d" role="img" aria-labelledby="nj-int-tl-title" '
	'xmlns="http://www.w3.org/2000/svg">' % (W, height)]
	minors = sum(1 for v, _ in releases if v[2] == 0)
	s.append('<title id="nj-int-tl-title">Timeline from the first commit (%s) and the %d releases from %s (%s) to %s '
	'(%s): %d minor or major releases, drawn as filled dots with their version above the axis, and %d patch '
	'releases, drawn as rings. The first commit is drawn as a diamond.</title>'
	% (first.isoformat(), len(releases), name(releases[0][0]), releases[0][1].isoformat(),
	name(releases[-1][0]), last.isoformat(), minors, len(releases) - minors))
	# year grid
	for year in range(start.year, end.year + 1):
	x = xof(datetime.date(year, 1, 1))
	s.append('<line class="nj-int-grid" x1="%.1f" y1="%d" x2="%.1f" y2="%d"/>' % (x, top - 4, x, axis + 8))
	if year < end.year:
	mid = xof(datetime.date(year, 7, 1))
	s.append('<text class="nj-int-year" x="%.1f" y="%d">%d</text>' % (mid, axis + 24, year))
	s.append('<line class="nj-int-axis" x1="%d" y1="%d" x2="%d" y2="%d"/>' % (LEFT, axis, RIGHT, axis))
	# major version spans
	majors = {}
	for version, date in releases:
	majors.setdefault(version[0], []).append(date)
	for major, dates in sorted(majors.items()):
	x0, x1 = xof(min(dates)), xof(max(dates))
	y = axis + 42
	s.append('<path class="nj-int-axis" fill="none" d="M%.1f %d V%d H%.1f V%d"/>' % (x0, y - 5, y, x1, y - 5))
	s.append('<text class="nj-int-major" x="%.1f" y="%d" text-anchor="%s">%d.x</text>'
	% ((x0 + x1) / 2 if x1 - x0 > 30 else x0, y + 17, "middle" if x1 - x0 > 30 else "start", major))
	# leaders and labels
	for x, row, text in labels:
	y = top - row * LABEL_ROW
	s.append('<line class="nj-int-leader" x1="%.1f" y1="%d" x2="%.1f" y2="%d"/>' % (x, y + 3, x, axis - 7))
	s.append('<text class="nj-int-label" x="%.1f" y="%d">%s</text>' % (x, y, text))
	# markers: the first commit, then one per date, patch rings first so that minor dots stay on top
	x = xof(FIRST_COMMIT)
	s.append('<g><title>First commit %s</title><circle class="nj-int-hit" cx="%.1f" cy="%d" r="9"/>'
	'<path class="nj-int-minor" d="M%.1f %d l7 -7 l7 7 l-7 7z" transform="translate(-7 0)"/></g>'
	% (FIRST_COMMIT.isoformat(), x, axis, x, axis))
	by_date = {}
	for version, date in releases:
	by_date.setdefault(date, []).append(version)
	groups = sorted(by_date.items(), key=lambda g: any(v[2] == 0 for v in g[1]))
	for date, versions in groups:
	minor = any(v[2] == 0 for v in versions)
	x = xof(date)
	tip = ", ".join(name(v) for v in sorted(versions)) + " released " + date.isoformat()
	s.append('<g><title>%s</title><circle class="nj-int-hit" cx="%.1f" cy="%d" r="9"/>'
	'<circle class="%s" cx="%.1f" cy="%d" r="%g"/></g>'
	% (tip, x, axis, "nj-int-minor" if minor else "nj-int-patch", x, axis, 6 if minor else 3.5))
	s.append('</svg>')
	return "\n".join(s) + "\n"


	releases = parse(PAGE.read_text(encoding="utf-8"))
	(OUT / "release_timeline.svg").write_text(draw(releases), encoding="utf-8")
	print("wrote", OUT / "release_timeline.svg", "with", len(releases), "releases")