Tweak README.rst

[cbrnr]

I've tried to tweak our README a little to make it easier to see what's important.

I did not touch the badges at the very top, but I would strongly suggest that we restrict ourselves to only one line (as rendered on GitHub). This means that at least one badge has to go. IMO, only the first three badges are important (PyPI, conda, DOI), the other four don't really contain super important information that needs to be presented at the top of the README (we already describe the forum in the document, so no need for this badge anyway).

To Do:

• Remove weird underlined space in badge table (need help from someone who actually knows rST).
• Streamline badge texts (e.g. always start with uppercase letter, etc.)

[sappelhoff]

if we need to remove a badge, then I'd remove the "bandit" one.

[drammock]

The two lines of badges don't bother me, but I wouldn't mind if the badges moved down below the big logo. While you're messing with the README there's also #11791 if you want to tackle that here

[hoechenberger]

The Hatch project uses a table, which I think looks very clean

https://github.com/pypa/hatch

[cbrnr]

I guess a table is OK, but I'd put it somewhere near the bottom of the document. I don't like the half-height empty first row though.

[hoechenberger]

Bottom I fine with me too :)

[cbrnr]

With badges in a table:

https://github.com/mne-tools/mne-python/blob/6705df27b9ae840838c3ddc5022959f2782070de/README.rst

The small logo doesn't look good though I think.

[cbrnr]

BTW, now that badges are neatly compiled in a table, we can add more! I would at least add a badge that links to our docs.

[hoechenberger]

@cbrnr Can you move the logo into the same line as the title? Is that possible?

I would also suggest to remove the information on installation via pip and instead only refer to our comprehensive install docs, esp since pip install mne only installs very limited functionality

[hoechenberger]

BTW, now that badges are neatly compiled in a table, we can add more! I would at least add a badge that links to our docs.

Sounds great

Hahaha

I love how, without hesitation, we moved from, remove all those stupid badges! to let's add all the badges! just because we're now approaching their layout differently 😃

[cbrnr]

The small logo doesn't look good at all, so we're back with the old one:

https://github.com/mne-tools/mne-python/blob/3cc27c5efcbffee72666a059695f67857e8e8e7d/README.rst

[drammock]

+1 for merge after fixing the duplicated word

[cbrnr]

Can you take a look at the to do at the top? I'd like to fix the underscore at least.

[hoechenberger]

Now that you mentioned it, I cannot unsee it anymore!! What have you done :)

[cbrnr]

Yes! Help! I've also seen this in other places now. It is strange that the previous two rows look OK although they also contain two badges.

[hoechenberger]

Is it a problem with that one specific badge perhaps?

[hoechenberger]

Multi-row with less vertical whitespace 🫣 (I know you tried)

... which leaves us with multi-column ... I'd bite for multi-column at this time

[cbrnr]

The "openssf best practices in progress 96%" badge is way too long IMO. Can we shorten it to at least "openssf 96%"? There's no official badge for this, but we could create our own.

Speaking of openssf, the badge would probably also get smaller if we fulfilled the following missing requirements:

1. "The project SHOULD respond to a majority (>50%) of enhancement requests in the last 2-12 months (inclusive)." – I guess we can set this to "yes"?
2. "The project MUST have at least one primary developer who knows how to design secure software. (See ‘details’ for the exact requirements.)"
3. "At least one of the project's primary developers MUST know of common kinds of errors that lead to vulnerabilities in this kind of software, as well as at least one method to counter or mitigate each of them."

For the last two points, I'd think that @drammock and/or @larsoner know about these things.

[hoechenberger]

I dare say I also fulfill 2./3., so I think we have multiple devs to tick that one off ✅

[cbrnr]

I think I would also qualify, but depending on how official this is going to be, I don't really want to be the one on the list 😆! So we need someone willing to be that person.

[larsoner]

I went through and updated a bunch of fields EDIT: on openssf. We are actually a few items away from gold I think.

@hoechenberger feel free to merge if you're happy

[larsoner]

... and I personally don't mind the badge being too long. The table is still plenty small. I'd rather stick with their badge than roll our own custom one

[drammock]

Speaking of openssf, the badge would probably also get smaller if we fulfilled the following missing requirements:

@larsoner has marked these as "satisfied" (and #12175 gives us a way to track the first one)

[cbrnr]

Perfect! I think it looks pretty good now then! The rST underscore thing is still bugging me, so if anyone has an idea what the problem could be, please LMK.

[larsoner]

I think the underscore is the best we can do at the moment for a reST substitution with a link unfortunately

[cbrnr]

I think the underscore is the best we can do at the moment for a reST substitution with a link unfortunately

So you are saying this is intentional behavior? I don't understand it though. Why can I put some badges side by side, whereas it obviously doesn't work with the Zenodo badge? (Note: I know almost nothing about reST!)

[larsoner]

Not intentional in the sense that it's desired, I thought it was just a side effect of us using reST with a substitution + link. But looking deeper I think it's a GitHub reST rendering bug seeing as SciPy doesn't use substitutions and also has a gap between logos with a hyperlinked _:

https://github.com/scipy/scipy/blob/main/README.rst

Not sure about Zenodo

[hoechenberger]

I think it's got something to do with the Zenodo SVG tbh

[hoechenberger]

When you use an inspector and select the surrounding <a> element, it behaves differently for Zenodo than for all the other badges

[cbrnr]

Please stop me anytime, I'm just trying to understand this mysterious behavior. So do you think this is a bug in reST (i.e., how reST converts the syntax to HTML)? Or a bug in a specific reST engine (if that's even a thing)? Or a bug in how GitHub renders reST?

[drammock]

When you use an inspector and select the surrounding <a> element, it behaves differently for Zenodo than for all the other badges

if someone is motivated to dig, the Bandit repo README doesn't use the underscore-to-denote-link approach at all, they do:

.. image:: path/to/image.svg
   :target: https://url/of/target/

and they still have the underscore.

Or a bug in how GitHub renders reST?

That is the direction I'm leaning, but I haven't dug in enough to be confident.

[hoechenberger]

Totally unrelated but it just crossed my mind, could you please check a11y implications of using a table without header? Is that acceptable at all?

[cbrnr]

Totally unrelated but it just crossed my mind, could you please check a11y implications of using a table without header? Is that acceptable at all?

Can you recommend a tool to do that?

[cbrnr]

I found this: https://www.powermapper.com/products/sortsite/rules/acchtmltablenoheaders/

I mean, it's already questionable if a table of badges are accessible in the first place.

[hoechenberger]

So it seems common screen readers ship with heuristics to deal with such tables. I hence think it's acceptable for us to omit the header, even if not considered a good practice

[drammock]

from @cbrnr's link:

If a data table has headers marked up using td, then change these to th.
If the table is only used for layout add role=presentation to the table element.

I'm not sure how much control we actually have here, since the rST is getting converted to HTML by GitHub, not by us. In terms of a11y, probably the best we can do is to make sure each badge has alt text, and make sure the alt text is actually good.

As for getting rid of the underscore, just throwing out ideas here. I looked at the rendering of Bandit's README, and the difference is this:

So maybe try separating the badges with a non-breaking space? (u+00A0)

[cbrnr]

I already tried with nbsps, it didn't work (b49f014).

[hoechenberger]

Shall we go ahead and merge here?

[larsoner]

Yep looks like there are approvals, thanks @cbrnr !