Skip to content

Commit 13fe03e

Browse files
samcunliffepaddyroddypre-commit-ci[bot]
authored
Improve accessibility of traffic lights: replacing 🟢🟠🔴 with JustTheDoc's labels. (#531)
An attempt to solve - #526 by replacing the emoji (same shape different colours) with a [JustTheDocs label](https://just-the-docs.com/docs/ui-components/labels/) UI component. Unfortunately, the JTD-flavoured markdown syntax for this is ```md Good {: .label .label-green} ``` ... that is to say: it needs two lines. And obviously, this doesn't work inside markdown tables. But once upon a time, I learned some HTML 🙃 so we can also access them as ```html <span class="foo"></span> ``` tags. ---- Now! This makes the markdown not look as beautiful/colourful/emojiful when viewed in GitHub... ![Screenshot 2025-04-11 at 16 07 24](https://github.com/user-attachments/assets/ba17275a-6169-40ca-b481-009adc5dffce) (though arguably more readable... which is perhaps the accessibility point.) ---- Here's what it looks like on the built pages: ![Screenshot 2025-04-11 at 16 04 10](https://github.com/user-attachments/assets/227dcafa-2e8f-4385-9595-f10807796ebb) ![Screenshot 2025-04-11 at 16 04 17](https://github.com/user-attachments/assets/893e1d5e-0445-4838-946a-8a6ab9ec85a6) --------- Co-authored-by: Patrick J. Roddy <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
1 parent 9171fa4 commit 13fe03e

17 files changed

+190
-191
lines changed

‎docs/index.md

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -40,13 +40,12 @@ are a good place to start.
4040

4141
### Traffic lights
4242

43-
Each item has an (opinionated) traffic light. The meaning of these is:
43+
Each item has an (opinionated) traffic light label. The meaning of these is:
4444

45-
- 🟢 At least one person in ARC uses this. We actively recommend using it above
45+
- <span class="label label-green">Best</span>: At least one person in ARC uses this. We actively recommend using it above
4646
other tools. It is the single recommended tool for a given purpose.
47-
- 🟠 We don't discourage using this, but it may duplicate functionality of a
48-
green tool.
49-
- 🔴 We actively discourage using this. This could be because it's no longer
47+
- <span class="label label-yellow">Good</span>: We don't discourage using this, but it may duplicate functionality of the <span class="label label-green">Best</span> tool.
48+
- <span class="label label-red">Avoid</span>: We actively discourage using this. This could be because it's no longer
5049
maintained, not open source, or difficult to use. Consider moving to
5150
alternatives if you're currently using something that's red. A reason for not
5251
using this is given.

‎docs/pages/benchmarking-profiling.md

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -5,29 +5,29 @@ layout: default
55

66
## Benchmarking
77

8-
| Name | Short description | 🚦 |
9-
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
10-
| [asv](https://asv.readthedocs.io/en/stable/) | A tool for benchmarking Python packages over their lifetime. Allows you to write benchmarks and then run them against every commit in the repository, to identify where performance increased or decreased. Comparative benchmarks can also be run, which can be useful for [running them in CI using GitHub runners](https://labs.quansight.org/blog/2021/08/github-actions-benchmarks). | 🟢 |
8+
| Name | Short description | 🚦 |
9+
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----------------------------------------: |
10+
| [asv](https://asv.readthedocs.io/en/stable/) | A tool for benchmarking Python packages over their lifetime. Allows you to write benchmarks and then run them against every commit in the repository, to identify where performance increased or decreased. Comparative benchmarks can also be run, which can be useful for [running them in CI using GitHub runners](https://labs.quansight.org/blog/2021/08/github-actions-benchmarks). | <span class="label label-green">Best</span> |
1111

1212
## Profiling
1313

1414
### Time
1515

16-
| Name | Short description | 🚦 |
17-
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
18-
| [pyinstrument](https://pyinstrument.readthedocs.io/en/stable) | Python profiler. Tells you how long individual lines of code take to run, so you can focus on the slowest part of your program to speed it up. | 🟢 |
19-
| [line_profiler](https://pypi.org/project/line-profiler/) | A tool for line-by-line profiling of functions. | 🟠 |
16+
| Name | Short description | 🚦 |
17+
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: |
18+
| [pyinstrument](https://pyinstrument.readthedocs.io/en/stable) | Python profiler. Tells you how long individual lines of code take to run, so you can focus on the slowest part of your program to speed it up. | <span class="label label-green">Best</span> |
19+
| [line_profiler](https://pypi.org/project/line-profiler/) | A tool for line-by-line profiling of functions. | <span class="label label-yellow">Good</span> |
2020

2121
### Memory
2222

23-
| Name | Short description | 🚦 |
24-
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
25-
| [memray](https://bloomberg.github.io/memray/) | Tracks and reports memory allocations, both in Python code and in compiled extension modules. It also has a [plugin](https://pytest-memray.readthedocs.io/en/latest/) for easy integration with pytest. Only works on Linux and macOS. | 🟠 |
26-
| [memory_profiler](https://pypi.org/project/memory-profiler/) | No longer actively maintained. A Python module for monitoring memory consumption of a process alongside line-by-line analysis of memory consumption. Might be a useful alternative to memray if you need to do memory profiling on Windows. | 🟠 |
23+
| Name | Short description | 🚦 |
24+
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: |
25+
| [memray](https://bloomberg.github.io/memray/) | Tracks and reports memory allocations, both in Python code and in compiled extension modules. It also has a [plugin](https://pytest-memray.readthedocs.io/en/latest/) for easy integration with pytest. Only works on Linux and macOS. | <span class="label label-yellow">Good</span> |
26+
| [memory_profiler](https://pypi.org/project/memory-profiler/) | No longer actively maintained. A Python module for monitoring memory consumption of a process alongside line-by-line analysis of memory consumption. Might be a useful alternative to memray if you need to do memory profiling on Windows. | <span class="label label-yellow">Good</span> |
2727

2828
### General/other tools
2929

30-
| Name | Short description | 🚦 |
31-
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------- | :-: |
32-
| [psutil](https://psutil.readthedocs.io/en/latest/) | System monitoring, profiling, limiting process resources and the management of running processes. | 🟢 |
33-
| [snakeviz](https://jiffyclub.github.io/snakeviz/) | Browser based graphical viewer for the output of Python’s cProfile module. | 🟢 |
30+
| Name | Short description | 🚦 |
31+
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------- | :-----------------------------------------: |
32+
| [psutil](https://psutil.readthedocs.io/en/latest/) | System monitoring, profiling, limiting process resources and the management of running processes. | <span class="label label-green">Best</span> |
33+
| [snakeviz](https://jiffyclub.github.io/snakeviz/) | Browser based graphical viewer for the output of Python’s cProfile module. | <span class="label label-green">Best</span> |

‎docs/pages/ci.md

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,15 @@ layout: default
55

66
## Continuous integration (CI)
77

8-
| Name | Short description | 🚦 |
9-
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
10-
| [GitHub Actions](https://docs.github.com/en/actions) | Continuous integration and continuous delivery platform (integrated with GitHub). | 🟢 |
11-
| [AppVeyor](https://www.appveyor.com/docs/) | Continuous integration and continuous delivery platform. | 🟠 |
12-
| [Bamboo](https://confluence.atlassian.com/bamboo/bamboo-documentation-289276551.html) | Atlassian continuous integration and continuous delivery platform. | 🟠 |
13-
| [Travis CI](https://docs.travis-ci.com/) | Continuous integration and continuous delivery platform. | 🟠 |
14-
| [pre-commit.ci](https://pre-commit.ci/) | A bot that adds a pre-commit job to your GitHub Actions CI, and can automatically fix most trivial linting failures. Free for open-source projects. | 🟢 |
8+
| Name | Short description | 🚦 |
9+
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: |
10+
| [GitHub Actions](https://docs.github.com/en/actions) | Continuous integration and continuous delivery platform (integrated with GitHub). | <span class="label label-green">Best</span> |
11+
| [AppVeyor](https://www.appveyor.com/docs/) | Continuous integration and continuous delivery platform. | <span class="label label-yellow">Good</span> |
12+
| [Bamboo](https://confluence.atlassian.com/bamboo/bamboo-documentation-289276551.html) | Atlassian continuous integration and continuous delivery platform. | <span class="label label-yellow">Good</span> |
13+
| [Travis CI](https://docs.travis-ci.com/) | Continuous integration and continuous delivery platform. | <span class="label label-yellow">Good</span> |
14+
| [pre-commit.ci](https://pre-commit.ci/) | A bot that adds a pre-commit job to your GitHub Actions CI, and can automatically fix most trivial linting failures. Free for open-source projects. | <span class="label label-green">Best</span> |
1515

16-
<details><summary> 🟢 explanation</summary><!-- markdownlint-disable-line MD033 -->
16+
<details><summary> <span class="label label-green">Best</span> explanation</summary><!-- markdownlint-disable-line MD033 -->
1717
We have many projects using GitHub CI and, it has good integration with GitHub itself, and is free for public repositories (with limited free monthly minutes for private repositories).
1818
</details>
1919

@@ -24,11 +24,11 @@ code with highlighting to show which lines are not executed by tests. See
2424
[testing](testing) for our recommendations on packages to generate code coverage
2525
during tests.
2626

27-
| Name | Short description | 🚦 |
28-
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
29-
| [Codecov](https://docs.codecov.com/docs) | Hosted service to report code coverage metrics. Occasionally slow to update after a report is updated, can be configured to add extra CI checks. This service is probably more widely used and is [free for both open-source and private projects](https://about.codecov.io/pricing/). | 🟢 |
30-
| [Coveralls](https://docs.coveralls.io/) | Hosted service to report code coverage metrics. Very similar to codecov and we don't strongly recommend one over the other. This service is only [free for open-source projects](https://coveralls.io/pricing). | 🟢 |
27+
| Name | Short description | 🚦 |
28+
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----------------------------------------: |
29+
| [Codecov](https://docs.codecov.com/docs) | Hosted service to report code coverage metrics. Occasionally slow to update after a report is updated, can be configured to add extra CI checks. This service is probably more widely used and is [free for both open-source and private projects](https://about.codecov.io/pricing/). | <span class="label label-green">Best</span> |
30+
| [Coveralls](https://docs.coveralls.io/) | Hosted service to report code coverage metrics. Very similar to codecov and we don't strongly recommend one over the other. This service is only [free for open-source projects](https://coveralls.io/pricing). | <span class="label label-green">Best</span> |
3131

32-
<details><summary> 🟢 explanation</summary> <!-- markdownlint-disable-line MD033 -->
33-
Both services are similar, so both 🟢.
32+
<details><summary> <span class="label label-green">Best</span> explanation</summary> <!-- markdownlint-disable-line MD033 -->
33+
Both services are similar, so both <span class="label label-green">Best</span>.
3434
</details>

0 commit comments

Comments
 (0)