github-milestone-roadmap 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. github_milestone_roadmap-0.1.0/.github/workflows/pre-commit.yml +17 -0
  2. github_milestone_roadmap-0.1.0/.github/workflows/pytest.yml +24 -0
  3. github_milestone_roadmap-0.1.0/.github/workflows/release.yml +39 -0
  4. github_milestone_roadmap-0.1.0/.gitignore +9 -0
  5. github_milestone_roadmap-0.1.0/.pre-commit-config.yaml +14 -0
  6. github_milestone_roadmap-0.1.0/CHANGELOG.md +28 -0
  7. github_milestone_roadmap-0.1.0/LICENSE +21 -0
  8. github_milestone_roadmap-0.1.0/PKG-INFO +134 -0
  9. github_milestone_roadmap-0.1.0/README.md +118 -0
  10. github_milestone_roadmap-0.1.0/examples/roadmap.toml +37 -0
  11. github_milestone_roadmap-0.1.0/pyproject.toml +44 -0
  12. github_milestone_roadmap-0.1.0/src/github_milestone_roadmap/__init__.py +8 -0
  13. github_milestone_roadmap-0.1.0/src/github_milestone_roadmap/build.py +169 -0
  14. github_milestone_roadmap-0.1.0/src/github_milestone_roadmap/changes.py +377 -0
  15. github_milestone_roadmap-0.1.0/src/github_milestone_roadmap/cli.py +142 -0
  16. github_milestone_roadmap-0.1.0/src/github_milestone_roadmap/config.py +304 -0
  17. github_milestone_roadmap-0.1.0/src/github_milestone_roadmap/static/app.js +577 -0
  18. github_milestone_roadmap-0.1.0/src/github_milestone_roadmap/static/index.html +49 -0
  19. github_milestone_roadmap-0.1.0/src/github_milestone_roadmap/static/styles.css +589 -0
  20. github_milestone_roadmap-0.1.0/tests/test_build.py +85 -0
  21. github_milestone_roadmap-0.1.0/tests/test_changes.py +207 -0
  22. github_milestone_roadmap-0.1.0/tests/test_config.py +87 -0
  23. github_milestone_roadmap-0.1.0/uv.lock +316 -0
@@ -0,0 +1,17 @@
1
+ name: pre-commit
2
+
3
+ on:
4
+ push:
5
+ branches:
6
+ - main
7
+ pull_request:
8
+
9
+ jobs:
10
+ pre-commit:
11
+ runs-on: ubuntu-latest
12
+ steps:
13
+ - uses: actions/checkout@v4
14
+ - uses: actions/setup-python@v5
15
+ with:
16
+ python-version: "3.12"
17
+ - uses: pre-commit/action@v3.0.1
@@ -0,0 +1,24 @@
1
+ name: pytest
2
+
3
+ on:
4
+ push:
5
+ branches:
6
+ - main
7
+ pull_request:
8
+
9
+ jobs:
10
+ pytest:
11
+ runs-on: ubuntu-latest
12
+ strategy:
13
+ matrix:
14
+ python-version: ["3.11", "3.12", "3.13"]
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+ with:
18
+ fetch-depth: 0 # tags are needed for the hatch-vcs version
19
+ - uses: astral-sh/setup-uv@v6
20
+ with:
21
+ python-version: ${{ matrix.python-version }}
22
+ - run: uv run --python ${{ matrix.python-version }} pytest
23
+ - name: Build example site
24
+ run: uv run --python ${{ matrix.python-version }} github-milestone-roadmap build --config examples/roadmap.toml --output _site
@@ -0,0 +1,39 @@
1
+ name: release
2
+
3
+ # Publishes to PyPI when a vX.Y.Z tag is pushed. Uses PyPI trusted publishing:
4
+ # the `github-milestone-roadmap` project on PyPI must list this repository,
5
+ # this workflow (release.yml) and the `pypi` environment as a trusted publisher.
6
+
7
+ on:
8
+ push:
9
+ tags:
10
+ - "v*"
11
+
12
+ jobs:
13
+ build:
14
+ runs-on: ubuntu-latest
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+ with:
18
+ fetch-depth: 0 # tags are needed for the hatch-vcs version
19
+ - uses: astral-sh/setup-uv@v6
20
+ - run: uv build
21
+ - uses: actions/upload-artifact@v4
22
+ with:
23
+ name: dist
24
+ path: dist/
25
+
26
+ publish:
27
+ needs: build
28
+ runs-on: ubuntu-latest
29
+ environment:
30
+ name: pypi
31
+ url: https://pypi.org/project/github-milestone-roadmap/
32
+ permissions:
33
+ id-token: write
34
+ steps:
35
+ - uses: actions/download-artifact@v4
36
+ with:
37
+ name: dist
38
+ path: dist/
39
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,9 @@
1
+ .DS_Store
2
+ node_modules/
3
+ .venv/
4
+ __pycache__/
5
+ *.egg-info/
6
+ dist/
7
+ build/
8
+ .pytest_cache/
9
+ .ruff_cache/
@@ -0,0 +1,14 @@
1
+ repos:
2
+ - repo: https://github.com/pre-commit/pre-commit-hooks
3
+ rev: v6.0.0
4
+ hooks:
5
+ - id: trailing-whitespace
6
+ - id: end-of-file-fixer
7
+ - id: check-toml
8
+ - id: check-yaml
9
+ - repo: https://github.com/astral-sh/ruff-pre-commit
10
+ rev: v0.15.22
11
+ hooks:
12
+ - id: ruff-check
13
+ args: [--fix]
14
+ - id: ruff-format
@@ -0,0 +1,28 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ## [v0.1.0](https://github.com/mllam/github-milestone-roadmap/releases/tag/v0.1.0) - 2026-11-17
11
+
12
+ First release.
13
+
14
+ ### Added
15
+
16
+ - Package the mllam roadmap page as the reusable `github-milestone-roadmap`
17
+ tool: `github-milestone-roadmap build` writes the static site for any set of
18
+ repositories described in a TOML config, and `github-milestone-roadmap changes`
19
+ (formerly `scripts/milestone_changes.py`) prints recent milestone additions
20
+ for the same repositories. Repositories can come from several owners.
21
+ [\#2](https://github.com/mllam/github-milestone-roadmap/pull/2), @leifdenby
22
+
23
+ ### Changed
24
+
25
+ - The site is no longer deployed from this repository. Sites that use the tool
26
+ build it in their own deploy workflow (mllam's roadmap is served at
27
+ https://mllam.github.io/roadmap from the `mllam/mllam.github.io` repository).
28
+ [\#2](https://github.com/mllam/github-milestone-roadmap/pull/2), @leifdenby
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 github-milestone-roadmap contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,134 @@
1
+ Metadata-Version: 2.5
2
+ Name: github-milestone-roadmap
3
+ Version: 0.1.0
4
+ Summary: Build a live roadmap website from GitHub release milestones across several repositories
5
+ Project-URL: Repository, https://github.com/mllam/github-milestone-roadmap
6
+ Project-URL: Changelog, https://github.com/mllam/github-milestone-roadmap/blob/main/CHANGELOG.md
7
+ Author: Leif Denby
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Classifier: Environment :: Console
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Topic :: Software Development :: Documentation
13
+ Requires-Python: >=3.11
14
+ Requires-Dist: httpx>=0.27
15
+ Description-Content-Type: text/markdown
16
+
17
+ # github-milestone-roadmap
18
+
19
+ Build a live roadmap website from GitHub release milestones across several
20
+ repositories.
21
+
22
+ The generated site is a single static page. It reads milestones, issues and
23
+ pull requests from the public GitHub API in the visitor's browser, so the
24
+ roadmap is always current without rebuilding the site. It is used for the
25
+ [mllam community roadmap](https://mllam.github.io/roadmap).
26
+
27
+ ## The milestone convention
28
+
29
+ Milestone names decide where an item appears:
30
+
31
+ - `vX.Y.Z`: the item is **on the roadmap** for that release.
32
+ - `vX.Y.Z (proposed)`: the item is **proposed** for that release.
33
+
34
+ For each release the page shows three lanes: open issues/PRs on the roadmap,
35
+ open proposed issues/PRs, and pull requests already merged into the `vX.Y.Z`
36
+ milestone. Open pull requests also show their review status. Milestones with
37
+ other names are ignored.
38
+
39
+ ## Usage
40
+
41
+ Write a `roadmap.toml` describing your roadmap (see
42
+ [`examples/roadmap.toml`](examples/roadmap.toml) for every option):
43
+
44
+ ```toml
45
+ title = "My Community Roadmap"
46
+ subtitle = "Upcoming work across our packages"
47
+ source_url = "https://github.com/my-org"
48
+
49
+ [home]
50
+ text = "My Community"
51
+ url = "/"
52
+
53
+ # One [[repos]] entry per repository; add as many as you like, in display order.
54
+ [[repos]]
55
+ owner = "my-org"
56
+ name = "my-package"
57
+ description = "What this package does."
58
+ ```
59
+
60
+ Then build the site:
61
+
62
+ ```sh
63
+ uvx github-milestone-roadmap build --config roadmap.toml --output _site/roadmap
64
+ ```
65
+
66
+ This writes `index.html`, `app.js`, `styles.css` and `config.json` to the
67
+ output directory. The page only uses relative paths, so it can be served from
68
+ any subpath.
69
+
70
+ ### In a GitHub Pages workflow
71
+
72
+ Pin the version so that roadmap tool updates reach your site only when you bump
73
+ it:
74
+
75
+ ```yaml
76
+ - uses: astral-sh/setup-uv@v6
77
+ - name: Build roadmap
78
+ run: uvx github-milestone-roadmap==0.1.0 build --config roadmap.toml --output _site/roadmap
79
+ - uses: actions/upload-pages-artifact@v3
80
+ with:
81
+ path: _site
82
+ ```
83
+
84
+ See the [mllam.github.io deploy workflow](https://github.com/mllam/mllam.github.io/blob/main/.github/workflows/pages.yml)
85
+ for a complete example.
86
+
87
+ ### API usage and caching
88
+
89
+ Without authentication, the GitHub API allows 60 requests per hour per
90
+ visitor. The page makes three requests per repository (open milestones, open
91
+ issues/PRs, recently closed PRs) plus one per displayed open pull request for
92
+ its review status. Responses are cached in the browser's `localStorage` for 15
93
+ minutes under the config's `cache_key`, and stale cached data is shown if the
94
+ rate limit is reached.
95
+
96
+ ## Milestone changes report
97
+
98
+ `changes` prints the issues and pull requests added to a `vX.Y.Z` milestone in
99
+ the last 24 hours across the configured repositories, grouped per repository
100
+ and version. The output is Markdown with nested lists, suitable for pasting
101
+ into Slack.
102
+
103
+ It uses the GraphQL API, so a GitHub token is required. With the
104
+ [`gh`](https://cli.github.com/) CLI logged in:
105
+
106
+ ```sh
107
+ uvx github-milestone-roadmap changes --config roadmap.toml --token "$(gh auth token)"
108
+ ```
109
+
110
+ or set `GITHUB_TOKEN` in the environment. Use `--hours N` to change the
111
+ look-back window.
112
+
113
+ ## Development
114
+
115
+ ```sh
116
+ uv run pytest
117
+ uv run pre-commit install # ruff lint and format on commit
118
+ ```
119
+
120
+ To preview the page locally:
121
+
122
+ ```sh
123
+ uv run github-milestone-roadmap build --config examples/roadmap.toml --output _site
124
+ python3 -m http.server --directory _site 8080
125
+ ```
126
+
127
+ Then visit http://localhost:8080. The page needs `config.json` from the build,
128
+ so opening `index.html` directly from disk will not work.
129
+
130
+ ## Releasing
131
+
132
+ Versions come from git tags (hatch-vcs). To release, update `CHANGELOG.md`,
133
+ merge to `main`, then tag `vX.Y.Z` on `main` and push the tag. The `release`
134
+ workflow publishes to PyPI with trusted publishing.
@@ -0,0 +1,118 @@
1
+ # github-milestone-roadmap
2
+
3
+ Build a live roadmap website from GitHub release milestones across several
4
+ repositories.
5
+
6
+ The generated site is a single static page. It reads milestones, issues and
7
+ pull requests from the public GitHub API in the visitor's browser, so the
8
+ roadmap is always current without rebuilding the site. It is used for the
9
+ [mllam community roadmap](https://mllam.github.io/roadmap).
10
+
11
+ ## The milestone convention
12
+
13
+ Milestone names decide where an item appears:
14
+
15
+ - `vX.Y.Z`: the item is **on the roadmap** for that release.
16
+ - `vX.Y.Z (proposed)`: the item is **proposed** for that release.
17
+
18
+ For each release the page shows three lanes: open issues/PRs on the roadmap,
19
+ open proposed issues/PRs, and pull requests already merged into the `vX.Y.Z`
20
+ milestone. Open pull requests also show their review status. Milestones with
21
+ other names are ignored.
22
+
23
+ ## Usage
24
+
25
+ Write a `roadmap.toml` describing your roadmap (see
26
+ [`examples/roadmap.toml`](examples/roadmap.toml) for every option):
27
+
28
+ ```toml
29
+ title = "My Community Roadmap"
30
+ subtitle = "Upcoming work across our packages"
31
+ source_url = "https://github.com/my-org"
32
+
33
+ [home]
34
+ text = "My Community"
35
+ url = "/"
36
+
37
+ # One [[repos]] entry per repository; add as many as you like, in display order.
38
+ [[repos]]
39
+ owner = "my-org"
40
+ name = "my-package"
41
+ description = "What this package does."
42
+ ```
43
+
44
+ Then build the site:
45
+
46
+ ```sh
47
+ uvx github-milestone-roadmap build --config roadmap.toml --output _site/roadmap
48
+ ```
49
+
50
+ This writes `index.html`, `app.js`, `styles.css` and `config.json` to the
51
+ output directory. The page only uses relative paths, so it can be served from
52
+ any subpath.
53
+
54
+ ### In a GitHub Pages workflow
55
+
56
+ Pin the version so that roadmap tool updates reach your site only when you bump
57
+ it:
58
+
59
+ ```yaml
60
+ - uses: astral-sh/setup-uv@v6
61
+ - name: Build roadmap
62
+ run: uvx github-milestone-roadmap==0.1.0 build --config roadmap.toml --output _site/roadmap
63
+ - uses: actions/upload-pages-artifact@v3
64
+ with:
65
+ path: _site
66
+ ```
67
+
68
+ See the [mllam.github.io deploy workflow](https://github.com/mllam/mllam.github.io/blob/main/.github/workflows/pages.yml)
69
+ for a complete example.
70
+
71
+ ### API usage and caching
72
+
73
+ Without authentication, the GitHub API allows 60 requests per hour per
74
+ visitor. The page makes three requests per repository (open milestones, open
75
+ issues/PRs, recently closed PRs) plus one per displayed open pull request for
76
+ its review status. Responses are cached in the browser's `localStorage` for 15
77
+ minutes under the config's `cache_key`, and stale cached data is shown if the
78
+ rate limit is reached.
79
+
80
+ ## Milestone changes report
81
+
82
+ `changes` prints the issues and pull requests added to a `vX.Y.Z` milestone in
83
+ the last 24 hours across the configured repositories, grouped per repository
84
+ and version. The output is Markdown with nested lists, suitable for pasting
85
+ into Slack.
86
+
87
+ It uses the GraphQL API, so a GitHub token is required. With the
88
+ [`gh`](https://cli.github.com/) CLI logged in:
89
+
90
+ ```sh
91
+ uvx github-milestone-roadmap changes --config roadmap.toml --token "$(gh auth token)"
92
+ ```
93
+
94
+ or set `GITHUB_TOKEN` in the environment. Use `--hours N` to change the
95
+ look-back window.
96
+
97
+ ## Development
98
+
99
+ ```sh
100
+ uv run pytest
101
+ uv run pre-commit install # ruff lint and format on commit
102
+ ```
103
+
104
+ To preview the page locally:
105
+
106
+ ```sh
107
+ uv run github-milestone-roadmap build --config examples/roadmap.toml --output _site
108
+ python3 -m http.server --directory _site 8080
109
+ ```
110
+
111
+ Then visit http://localhost:8080. The page needs `config.json` from the build,
112
+ so opening `index.html` directly from disk will not work.
113
+
114
+ ## Releasing
115
+
116
+ Versions come from git tags (hatch-vcs). To release, update `CHANGELOG.md`,
117
+ merge to `main`, then tag `vX.Y.Z` on `main` and push the tag. The `release`
118
+ workflow publishes to PyPI with trusted publishing.
@@ -0,0 +1,37 @@
1
+ # Example configuration for github-milestone-roadmap.
2
+ # This is the configuration used for https://mllam.github.io/roadmap
3
+
4
+ # Browser tab title (required).
5
+ title = "MLLAM Roadmap"
6
+ # Main heading (default: "Community Roadmap").
7
+ heading = "Community Roadmap"
8
+ # Line under the heading (default: none).
9
+ subtitle = "Upcoming work across the MLLAM packages"
10
+ # <meta name="description"> (default: subtitle, else title).
11
+ description = "Roadmap for the MLLAM community packages."
12
+ # GitHub link in the top-right corner (default: no link).
13
+ source_url = "https://github.com/mllam"
14
+ # Prefix for the browser cache of GitHub API responses (default: slug of title).
15
+ # Give each roadmap on the same domain its own key.
16
+ cache_key = "mllam-roadmap"
17
+
18
+ # Brand link in the top-left corner (default: text = title, url = "/").
19
+ [home]
20
+ text = "MLLAM"
21
+ url = "/"
22
+
23
+ # Repositories, in display order. `name` must be unique: it is the page anchor.
24
+ [[repos]]
25
+ owner = "mllam"
26
+ name = "neural-lam"
27
+ description = "Machine learning weather model training and inference package."
28
+
29
+ [[repos]]
30
+ owner = "mllam"
31
+ name = "mllam-data-prep"
32
+ description = "Data preparation workflows for MLLAM model development."
33
+
34
+ [[repos]]
35
+ owner = "mllam"
36
+ name = "weather-model-graphs"
37
+ description = "Graph structures and utilities for weather model domains."
@@ -0,0 +1,44 @@
1
+ [build-system]
2
+ requires = ["hatchling", "hatch-vcs"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "github-milestone-roadmap"
7
+ dynamic = ["version"]
8
+ description = "Build a live roadmap website from GitHub release milestones across several repositories"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "Leif Denby" }]
14
+ dependencies = ["httpx>=0.27"]
15
+ classifiers = [
16
+ "Programming Language :: Python :: 3",
17
+ "Environment :: Console",
18
+ "Topic :: Software Development :: Documentation",
19
+ ]
20
+
21
+ [project.urls]
22
+ Repository = "https://github.com/mllam/github-milestone-roadmap"
23
+ Changelog = "https://github.com/mllam/github-milestone-roadmap/blob/main/CHANGELOG.md"
24
+
25
+ [project.scripts]
26
+ github-milestone-roadmap = "github_milestone_roadmap.cli:main"
27
+
28
+ [dependency-groups]
29
+ dev = ["pytest>=8", "pre-commit>=3"]
30
+
31
+ [tool.hatch.version]
32
+ source = "vcs"
33
+
34
+ [tool.hatch.build.targets.wheel]
35
+ packages = ["src/github_milestone_roadmap"]
36
+
37
+ [tool.ruff]
38
+ line-length = 88
39
+
40
+ [tool.ruff.lint]
41
+ select = ["E", "F", "I", "UP", "B"]
42
+
43
+ [tool.pytest.ini_options]
44
+ testpaths = ["tests"]
@@ -0,0 +1,8 @@
1
+ """Build a live roadmap website from GitHub release milestones."""
2
+
3
+ from importlib.metadata import PackageNotFoundError, version
4
+
5
+ try:
6
+ __version__ = version("github-milestone-roadmap")
7
+ except PackageNotFoundError: # pragma: no cover - only when not installed
8
+ __version__ = "unknown"
@@ -0,0 +1,169 @@
1
+ """Write the static roadmap site for a configuration."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from html import escape
7
+ from importlib.resources import files
8
+ from pathlib import Path
9
+ from string import Template
10
+
11
+ from . import __version__
12
+ from .config import RoadmapConfig
13
+
14
+ STATIC_ASSETS = ("app.js", "styles.css")
15
+
16
+ GITHUB_ICON_PATH = (
17
+ "M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 "
18
+ "0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13"
19
+ "-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07"
20
+ "-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08"
21
+ "-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82A7.65 7.65 0 0 1 8 3.86c.68 0 1.36"
22
+ ".09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27"
23
+ ".82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93"
24
+ "-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8Z"
25
+ )
26
+
27
+
28
+ def read_static_text(name: str) -> str:
29
+ """Read a file shipped in the package's ``static`` folder.
30
+
31
+ Parameters
32
+ ----------
33
+ name : str
34
+ File name inside ``static``.
35
+
36
+ Returns
37
+ -------
38
+ str
39
+ File contents.
40
+ """
41
+ return (
42
+ files("github_milestone_roadmap")
43
+ .joinpath("static", name)
44
+ .read_text(encoding="utf-8")
45
+ )
46
+
47
+
48
+ def render_source_link(source_url: str) -> str:
49
+ """Render the GitHub link shown in the top-right corner.
50
+
51
+ Parameters
52
+ ----------
53
+ source_url : str
54
+ Link target; empty means no link.
55
+
56
+ Returns
57
+ -------
58
+ str
59
+ HTML for the link, or an empty string.
60
+ """
61
+ if not source_url:
62
+ return ""
63
+ return (
64
+ f' <a class="github-link" href="{escape(source_url)}" '
65
+ 'rel="noreferrer">\n'
66
+ ' <svg viewBox="0 0 16 16" aria-hidden="true" focusable="false">\n'
67
+ f' <path d="{GITHUB_ICON_PATH}" />\n'
68
+ " </svg>\n"
69
+ " <span>GitHub</span>\n"
70
+ " </a>"
71
+ )
72
+
73
+
74
+ def render_index_html(config: RoadmapConfig) -> str:
75
+ """Fill the ``index.html`` template from a configuration.
76
+
77
+ All configuration values are HTML-escaped.
78
+
79
+ Parameters
80
+ ----------
81
+ config : RoadmapConfig
82
+ The roadmap configuration.
83
+
84
+ Returns
85
+ -------
86
+ str
87
+ The rendered page.
88
+ """
89
+ repo_links = "\n".join(
90
+ f' <a href="#{escape(repo.name)}">{escape(repo.name)}</a>'
91
+ for repo in config.repos
92
+ )
93
+ subtitle_paragraph = (
94
+ f' <p class="subtitle">{escape(config.subtitle)}</p>'
95
+ if config.subtitle
96
+ else ""
97
+ )
98
+ template = Template(read_static_text("index.html"))
99
+ return template.substitute(
100
+ title=escape(config.title),
101
+ heading=escape(config.heading),
102
+ description=escape(config.description),
103
+ home_url=escape(config.home.url),
104
+ home_text=escape(config.home.text),
105
+ source_link=render_source_link(config.source_url),
106
+ subtitle_paragraph=subtitle_paragraph,
107
+ repo_links=repo_links,
108
+ version=escape(__version__),
109
+ )
110
+
111
+
112
+ def build_runtime_config(config: RoadmapConfig) -> dict[str, object]:
113
+ """Build the ``config.json`` content that ``app.js`` reads in the browser.
114
+
115
+ Parameters
116
+ ----------
117
+ config : RoadmapConfig
118
+ The roadmap configuration.
119
+
120
+ Returns
121
+ -------
122
+ dict
123
+ JSON-serialisable runtime configuration.
124
+ """
125
+ return {
126
+ "cache_key": config.cache_key,
127
+ "repos": [
128
+ {"owner": repo.owner, "name": repo.name, "description": repo.description}
129
+ for repo in config.repos
130
+ ],
131
+ }
132
+
133
+
134
+ def build_site(config: RoadmapConfig, output_dir: Path) -> list[Path]:
135
+ """Write the roadmap site into a directory.
136
+
137
+ Existing files with the same names are overwritten; other files in
138
+ ``output_dir`` are left untouched.
139
+
140
+ Parameters
141
+ ----------
142
+ config : RoadmapConfig
143
+ The roadmap configuration.
144
+ output_dir : Path
145
+ Directory to write into; created if missing.
146
+
147
+ Returns
148
+ -------
149
+ list of Path
150
+ The files written.
151
+ """
152
+ output_dir.mkdir(parents=True, exist_ok=True)
153
+ written: list[Path] = []
154
+
155
+ index_path = output_dir / "index.html"
156
+ index_path.write_text(render_index_html(config), encoding="utf-8")
157
+ written.append(index_path)
158
+
159
+ for name in STATIC_ASSETS:
160
+ path = output_dir / name
161
+ path.write_text(read_static_text(name), encoding="utf-8")
162
+ written.append(path)
163
+
164
+ config_path = output_dir / "config.json"
165
+ config_path.write_text(
166
+ json.dumps(build_runtime_config(config), indent=2) + "\n", encoding="utf-8"
167
+ )
168
+ written.append(config_path)
169
+ return written