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.
- github_milestone_roadmap-0.1.0/.github/workflows/pre-commit.yml +17 -0
- github_milestone_roadmap-0.1.0/.github/workflows/pytest.yml +24 -0
- github_milestone_roadmap-0.1.0/.github/workflows/release.yml +39 -0
- github_milestone_roadmap-0.1.0/.gitignore +9 -0
- github_milestone_roadmap-0.1.0/.pre-commit-config.yaml +14 -0
- github_milestone_roadmap-0.1.0/CHANGELOG.md +28 -0
- github_milestone_roadmap-0.1.0/LICENSE +21 -0
- github_milestone_roadmap-0.1.0/PKG-INFO +134 -0
- github_milestone_roadmap-0.1.0/README.md +118 -0
- github_milestone_roadmap-0.1.0/examples/roadmap.toml +37 -0
- github_milestone_roadmap-0.1.0/pyproject.toml +44 -0
- github_milestone_roadmap-0.1.0/src/github_milestone_roadmap/__init__.py +8 -0
- github_milestone_roadmap-0.1.0/src/github_milestone_roadmap/build.py +169 -0
- github_milestone_roadmap-0.1.0/src/github_milestone_roadmap/changes.py +377 -0
- github_milestone_roadmap-0.1.0/src/github_milestone_roadmap/cli.py +142 -0
- github_milestone_roadmap-0.1.0/src/github_milestone_roadmap/config.py +304 -0
- github_milestone_roadmap-0.1.0/src/github_milestone_roadmap/static/app.js +577 -0
- github_milestone_roadmap-0.1.0/src/github_milestone_roadmap/static/index.html +49 -0
- github_milestone_roadmap-0.1.0/src/github_milestone_roadmap/static/styles.css +589 -0
- github_milestone_roadmap-0.1.0/tests/test_build.py +85 -0
- github_milestone_roadmap-0.1.0/tests/test_changes.py +207 -0
- github_milestone_roadmap-0.1.0/tests/test_config.py +87 -0
- 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,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
|