DOC: Document code contributors on website

[larsoner]

This gets us started on keeping track of code contributions to MNE, the first part of #11605.

1. Create a "Contributors" page, and link to it from the main landing page

2. Add a "Code Credit" heading on that page, mentioning eventually we'll add other stuff.

3. Populate it with code credit based on lines changed in commits in MNE-Python:

   1. Overall changes to MNE-Python
   2. submodule-by-submodule credit

We have a lot of contributors and a lot of modules, so it's tough to get all the information in there. There are lots of potential ways to do this, what to include, how to show it -- and thus a lot of potential bike shedding, so we should probably just try to make sure what's here is an improvement over the author lists we currently use. Let's not shoot for perfection here but just "good enough"!

Still some stuff to do:

• Manually run and create the page
• Converge on the idea it's actually better
• Make the page rebuild, likely by running on CircleCI (or opt-in locally), perhaps in a directive rather than writing an RST file
• Ensure that the line counts are actually correct / reasonable, considering the squash+merge (new) vs standard merge (old) ways of doing things. I think it's probably not correct yet, but I'll think on it. (I started writing something with the gh command-line tool, but querying every merged PR and get files changed and lines changed in each file takes forever. Getting the merge commit -- so that we could then use the git history to figure things out -- sometimes returns commit hashes that don't exist in our codebase. So it's not trivial.)
• Get reviews
• Unzip prs.zip
• Merge
• Remove author names from mne/ files in separate PR

[larsoner]

Frontpage

Links to

https://output.circle-artifacts.com/output/job/1d4da1a2-6f08-4643-b1f9-16582ba5a3df/artifacts/0/html/credit.html

[agramfort]

looks nice !

…

Message ID: ***@***.***>

[larsoner]

Okay @drammock I think I'm ready for review here!

What I came up with was:

1. Having separate doc/sphinxext/prs/<pr_num>.json files, one per PR, with the info we need to come up with code credit. Eventually if we want we can add other stuff like PR comment counts to those, and maybe issue comment counts in issues/<issue_num>.json or whatever. So I think the format is pretty flexible.
2. Getting the change info is done using PyGithub in tools/dev/update_credit_json.py so we stay Pythonic. Only downside is that the initial gathering of data is quite slow. But incremental monthly updates should be fast, and I've added a GitHub action that will eventually run monthly to do it for us. This ultimately seemed preferable over using, say, git diff locally because PyGithub gives us easier access to more info and future extensibility, and also the files-changed-in-PR is something we get directly there, and something that was really quite difficult using git locally (for me at least!).
3. Mapping the change counts to a doc/credit.rst file is done in tools/dev/update_credit_rst.py, and consumes the .json files. This does all sorts of accounting stuff, like mapping between author names, grouping into module types, etc. And then it takes that info and decides how to present it, which is as author badges embeddeding in module cards. Lots of opinionated choices here that we can tweak (maybe mostly in follow-up PRs?) but it's hopefully better than what we have in main already.

For ease of reviewing, I zipped the json files to a single zip, as I assumed that without doing so the Files page on this PR was going to be unusable. So once we agree this is ready for merge, I'll go back to individual .json files, make sure it still looks okay, and merge.

[drammock]

did interactive review with @larsoner in real-time, hence no in-line suggestions. Approving on assumption that he took good notes and will fix everything we discussed.

These are explicitly NOT in scope for this PR (but can be in follow-up PRs):

• tweaks to visual presentation
• changes to which modules we show credit for
• adding additional metrics (such as PR reviews) --- again, we want to do this, and can/should do so in follow-up PRs.
• performance enhancements relating to the GH API queries / JSON parsing (I'm convinced that it's fast enough for now)

[larsoner]

Also based on sphinx-doc/sphinx#8791 I'm adding -q to our linkcheck and checking to see if it's a suitable replacement for the grep we used to do since here conveniently I want to linkcheck anyway.

Will merge assuming everything works!

[britta-wstnr]

Nice, I like it!
One nitpick - if I convert to greyscale, the two colors for the top 10% contributors and rest are not distinguishable anymore:

Can we pick colors that are more easily distinguishable (assuming this would be an easy fix)?

[larsoner]

Okay changed to something with more contrast that looks okay in grayscale, will merge once I manually check by eye it rendered correctly!

[larsoner]

FYI @drammock I ended up changing the structure a bit. I realized that having a credit.rst in our code history that gets updated with thousands of badges is less than ideal -- it'll change a lot and bloat things I think. So instead now I have it create a doc/code_credit.inc on the fly (it's very fast) at the start of the doc build so that we don't have to keep it in our history. In theory this could instead be a directive, but I think it's actually nicer as a .inc because you can inspect it after it's generated, don't have to deal with docutils and nested parsing at all, etc.