Skip to content

Commit 919a900

Browse files
1ucian01ucian0
authored
Initial documentation on badges for qisk.it/ecosystem-badges (#1122)
1 parent d862cc8 commit 919a900

6 files changed

Lines changed: 94 additions & 24 deletions

File tree

‎docs/badges.md‎

Lines changed: 26 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,35 @@
1-
---
2-
hide:
3-
- navigation
4-
- toc
5-
---
6-
71
# Badges
82

3+
Projects of the [Qiskit Ecosystem](https://qisk.it/ecosystem) are invited to proudly display it in their `README.md` file. See [How to add ecosystem badge in your README](#style).
4+
The badge is also a way to signal the project maintainer the [membership status](../status/):
5+
6+
* Regular member:
7+
* Under revision:
8+
* Alumni:
9+
10+
## How to add the ecosystem badge in the project README file
11+
912
Once your project is part of the [Qiskit Ecosystem website](https://qisk.it/ecosystem), you can add the badge to your `README.md`:
1013

1114
1. Find your project in the following table.
12-
2. Copy the code in **Markdown code** column.
15+
2. Copy the `markdown` code.
1316
3. Paste it into your `README.md`.
1417

15-
<!--
16-
The following table is generated by `python manager.py members update_badge_list`
17-
DIRECT CHANGES ARE GOING TO BE OVERWRITTEN AUTOMATICALLY
18-
Submit an issue if you want to change something
19-
-->
18+
See [Change the badge style](#change-the-badge-style) on how to change the badge style.
2019

2120
{{ read_raw('docs/assets/badges_table.md') }}
21+
22+
## Change the badge style
23+
24+
To change the badge style, PR [the project toml file](https://github.com/Qiskit/ecosystem/tree/main/resources/members) changing the `badge.style` entry to one of these possible values:
25+
26+
`flat`: ![Qiskit Ecosystem](https://img.shields.io/endpoint?url=https://qiskit.github.io/ecosystem/b/example_flat)
27+
28+
`flat-square`: ![Qiskit Ecosystem](https://img.shields.io/endpoint?url=https://qiskit.github.io/ecosystem/b/example_flat-square)
29+
30+
`plastic`: ![Qiskit Ecosystem](https://img.shields.io/endpoint?url=https://qiskit.github.io/ecosystem/b/example_plastic)
31+
32+
`for-the-badge`: ![Qiskit Ecosystem](https://img.shields.io/endpoint?url=https://qiskit.github.io/ecosystem/b/example_for-the-badge)
33+
34+
`social`: ![Qiskit Ecosystem](https://img.shields.io/endpoint?url=https://qiskit.github.io/ecosystem/b/example_social)
35+

‎ecosystem/cli/members.py‎

Lines changed: 64 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ class CliMembers:
2323
Each public method of this class is CLI command
2424
and arguments for method are options/flags for this command.
2525
26-
Ex: `python manager.py members update_badges`
26+
Ex: `python manager.py members update_badge`
2727
"""
2828

2929
def __init__(self, root_path: Optional[str] = None):
@@ -74,11 +74,61 @@ def add_repo_2db(
7474
)
7575
self.dao.write(new_repo)
7676

77-
def create_badge_endpoints(self, name=None, output_directory: str = None):
78-
"""TODO."""
77+
def create_badge_endpoints(
78+
self, name: str = None, example: str = None, output_directory: str = None
79+
):
80+
"""Creates the JSON files in to be deployed in qiskit.github.io/ecosystem/b/<jsonfile>
81+
so they can be consumed by
82+
https://img.shields.io/endpoint?url=https://qiskit.github.io/ecosystem/b/<jsonfile>
83+
84+
Args:
85+
name: If <name> is not given, runs on all the members. Otherwise, all the members
86+
with name_id that contains <name> as substring are updated.
87+
example: If given, creates example badges for a ficticious project with that name. For
88+
example -e "Qiskit Banana Compiler" is currectly used in qisk.it/ecosystem-badges
89+
as an example. If not given, it does not create the example endpoints.
90+
output_directory: directory in which it saves the json files. By default, ./badges
91+
"""
7992
if not output_directory:
8093
output_directory = os.path.join(self.current_dir, "badges")
8194
Path(output_directory).mkdir(parents=True, exist_ok=True)
95+
if example:
96+
for style in ["flat", "flat-square", "plastic", "for-the-badge", "social"]:
97+
data = {
98+
"schemaVersion": 1,
99+
"label": "Qiskit Ecosystem",
100+
"namedLogo": "Qiskit",
101+
"message": example,
102+
"color": "6929C4",
103+
"isError": "true",
104+
"style": style,
105+
}
106+
filename = f"example_{style}"
107+
with open(os.path.join(output_directory, filename), "w") as outfile:
108+
json.dump(data, outfile, indent=4)
109+
self.logger.info(
110+
"Example Badge endpoint (style=%s): %s",
111+
style,
112+
os.path.join(output_directory, filename),
113+
)
114+
for message in "Alumni", "Under revision":
115+
data = {
116+
"schemaVersion": 1,
117+
"label": "Qiskit Ecosystem",
118+
"namedLogo": "Qiskit",
119+
"message": message,
120+
"color": "c46929" if message == "Under revision" else "6929C4",
121+
"isError": "true",
122+
"style": "flat",
123+
}
124+
filename = f"example_{slugify(message)}"
125+
with open(os.path.join(output_directory, filename), "w") as outfile:
126+
json.dump(data, outfile, indent=4)
127+
self.logger.info(
128+
"Example Badge endpoint (status=%s): %s",
129+
message,
130+
os.path.join(output_directory, filename),
131+
)
82132
for project in self.dao.get_all(name):
83133
# Create a json to be consumed by https://shields.io/badges/endpoint-badge
84134
if project.badge is None:
@@ -205,24 +255,30 @@ def update_badge_list(self):
205255
projects = []
206256
for project in self.dao.get_all():
207257
if project.badge is None:
258+
self.logger.warning(
259+
"badge not found for %s (%s)",
260+
project.name_id,
261+
project.name,
262+
)
208263
continue
209264
projects.append(
210-
(project.name, project.badge, project.badge_md, project.name_id)
265+
(project.name, project.badge.url, project.badge_md, project.name_id)
211266
)
212267

213268
projects.sort(key=lambda x: re.sub("[^A-Za-z0-9]+", "", x[0]).lower())
214269

215270
lines = [
216271
"",
217272
"<table>",
218-
"<tr><th>Member</th><th>Badge (click for full size)</th><th>Markdown code</th></tr>",
273+
"<tr><th>Member</th><th>Badge (click for full size) and MarkDown code</th></tr>",
274+
"",
219275
]
220276
for name, badge, badge_md, name_id in projects:
221277
lines.append(
222-
'<tr><td><a href="https://github.com/Qiskit/ecosystem/tree/main/ecosystem"'
278+
'<tr><td><a href="https://github.com/Qiskit/ecosystem/tree/main'
223279
f'/resources/members/{name_id}.toml">{name}</a></td>'
224-
f'<td><a href="{badge}"><img src="{badge}" /></a></td>'
225-
f"<td>\n\n```markdown\n{badge_md}\n```\n\n</td>"
280+
f'<td><a href="{badge}"><img src="{badge}" /></a><br/>'
281+
f"\n\n```markdown\n{badge_md} \n```\n\n</td>"
226282
"</tr>"
227283
)
228284
lines.append("</table>\n")

‎ecosystem/member.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -163,7 +163,7 @@ def name_id(self):
163163
def badge_md(self):
164164
"""Markdown with the badge for README"""
165165
return (
166-
f"[![Qiskit Ecosystem]({self.badge})](https://qisk.it/e)"
166+
f"[![Qiskit Ecosystem]({self.badge.url})](https://qisk.it/e)"
167167
if self.badge
168168
else None
169169
)

‎mkdocs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,4 +29,4 @@ nav:
2929
- Qiskit Pattern steps: pattern_steps.md
3030
- Interfaces: interfaces.md
3131
- Maturity: maturity.md
32-
- Badges: badges.md
32+
- Badges: badges.md

‎tests/github/test_templates.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ def test_interfaces(self):
6464
)
6565

6666
def test_maturity(self):
67-
"""maturity classification in the template should exist in resources/classifications.toml"""
67+
"""maturity classification in the template should exist in classifications.toml"""
6868
for section in self.issue_template["body"]:
6969
if "id" in section and section["id"] == "maturity":
7070
self.assertIn("attributes", section)

‎tox.ini‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ allowlist_externals =
4040
cp
4141
basepython = python3
4242
commands =
43-
bash -ec "python manager.py members create_badge_endpoints -o b/"
43+
bash -ec "python manager.py members create_badge_endpoints -e 'Qiskit Banana Compiler' -o b/"
4444
bash -ec "python manager.py members update_docs_assets"
4545
bash -ec "mkdocs build -d website/"
4646
bash -ec "python manager.py build --output website/index.html"

0 commit comments

Comments
 (0)