DOC: Document code contributors on website (#12774)

.circleci/config.yml

@@ -433,13 +433,9 @@ jobs:
             mne sys_info -pd
       - run:
           name: make linkcheck
+          no_output_timeout: 40m
           command: |
             make -C doc linkcheck
-      - run:
-          name: make linkcheck-grep
-          when: always
-          command: |
-            make -C doc linkcheck-grep
       - store_artifacts:
           path: doc/_build/linkcheck
           destination: linkcheck

.git-blame-ignore-revs

@@ -1,7 +1,14 @@
-e81ec528a42ac687f3d961ed5cf8e25f236925b0  # black
-12395f9d9cf6ea3c72b225b62e052dd0d17d9889  # YAML indentation
-d6d2f8c6a2ed4a0b27357da9ddf8e0cd14931b59  # isort
-e7dd1588013179013a50d3f6b8e8f9ae0a185783  # ruff format
-e39995d9be6fc831c7a4a59f09b7a7c0a41ae315  # percent formatting
-940ac9553ce42c15b4c16ecd013824ca3ea7244a  # whitespace
-1c5b39ff1d99bbcb2fc0e0071a989b3f3845ff30  # ruff UP028
+# PR number should follow the commit number so that our code credit
+# can parse this file correctly:
+d71e497dcf6f98e19eb81e82e641404a71d2d663  # 1420, split up viz.py
+203a96cbba2732d2e349a8f96065e74bbfd2a53b  # 5862, split utils.py
+ff349f356edb04e1b5f0db13deda8d1a20aca351  # 6767, move around manual parts
+31a83063557fbd54d898f00f9527ffc547888395  # 10407, alphabetize docdict
+e81ec528a42ac687f3d961ed5cf8e25f236925b0  # 11667, black
+12395f9d9cf6ea3c72b225b62e052dd0d17d9889  # 11868, YAML indentation
+d6d2f8c6a2ed4a0b27357da9ddf8e0cd14931b59  # 12097, isort
+e7dd1588013179013a50d3f6b8e8f9ae0a185783  # 12261, ruff format
+940ac9553ce42c15b4c16ecd013824ca3ea7244a  # 12533, whitespace
+e39995d9be6fc831c7a4a59f09b7a7c0a41ae315  # 12588, percent formatting
+1c5b39ff1d99bbcb2fc0e0071a989b3f3845ff30  # 12603, ruff UP028
+b8b168088cb474f27833f5f9db9d60abe00dca83  # 12779, PR JSONs

.github/workflows/credit.yml

@@ -0,0 +1,43 @@
+name: Contributor credit
+
+on:  # yamllint disable-line rule:truthy
+  # Scheduled actions only run on the main repo branch, which is exactly what we want
+  schedule:
+    # TODO: After making sure it works in `main` for a while, switch to monthly
+    # - cron: '0 0 1 * *'  # first day of the month at midnight
+    - cron: '0 0 * * *'  # every day at midnight
+
+permissions:
+  pull-requests: write
+
+jobs:
+  update_credit:
+    name: Update
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ github.token }}
+      GITHUB_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install pygithub -e .
+      - run: git checkout -b credit
+      - run: python tools/dev/update_credit_json.py
+      - run: python tools/dev/update_credit_rst.py
+      - run: git add -f doc/sphinxext/prs/*.json
+      - run: |
+          git diff && git status --porcelain
+          if [[ $(git status --porcelain) ]]; then
+            echo "dirty=true" >> $GITHUB_OUTPUT
+          fi
+        id: status
+      - name: Create PR
+        run: |
+          set -xeo pipefail
+          git config --global user.email "114827586+autofix-ci[bot]@users.noreply.github.com"
+          git config --global user.name "autofix-ci[bot]"
+          git commit -am "MAINT: Update code credit"
+          gh pr create -B main -H credit --title "MAINT: Update code credit" --body "Created by \"${{ github.workflow }}\" GitHub action." --label "no-changelog-entry-needed"
+        if: steps.status.outputs.dirty == 'true'

.gitignore

@@ -97,7 +97,7 @@ cover
 
 .venv/
 venv/
-*.json
+/*.json
 !codemeta.json
 .hypothesis/
 .ruff_cache/

.pre-commit-config.yaml

@@ -6,19 +6,20 @@ repos:
       - id: ruff
         name: ruff lint mne
         args: ["--fix"]
-        files: ^mne/
+        files: ^mne/|^tools/
+        exclude: vulture_allowlist.py
       - id: ruff
         name: ruff lint mne preview
         args: ["--fix", "--preview", "--select=NPY201"]
-        files: ^mne/
+        files: ^mne/|^tools/
       - id: ruff
         name: ruff lint doc, tutorials, and examples
         # D103: missing docstring in public function
         # D400: docstring first line must end with period
         args: ["--ignore=D103,D400", "--fix"]
         files: ^doc/|^tutorials/|^examples/
       - id: ruff-format
-        files: ^mne/|^doc/|^tutorials/|^examples/
+        files: ^mne/|^doc/|^tutorials/|^examples/|^tools/
 
   # Codespell
   - repo: https://github.com/codespell-project/codespell
@@ -27,7 +28,7 @@ repos:
       - id: codespell
         additional_dependencies:
           - tomli
-        files: ^mne/|^doc/|^examples/|^tutorials/
+        files: ^mne/|^doc/|^examples/|^tutorials/|^tools/
         types_or: [python, bib, rst, inc]
 
   # yamllint
@@ -45,13 +46,15 @@ repos:
         additional_dependencies:
           - tomli
         files: ^doc/.*\.(rst|inc)$
+        # Credit is problematic because we generate an include on the fly
+        exclude: ^doc/credit.rst$
 
   # sorting
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.6.0
     hooks:
       - id: file-contents-sorter
-        files: ^doc/changes/names.inc
+        files: ^doc/changes/names.inc|^.mailmap
         args: ["--ignore-case"]
 
 # The following are too slow to run on local commits, so let's only run on CIs:

doc/.gitignore

@@ -0,0 +1 @@
+/code_credit.inc

doc/Makefile

@@ -65,10 +65,7 @@ html_dev-noplot: html-noplot
 html_dev-front: html-front
 
 linkcheck:
-	@$(SPHINXBUILD) -b linkcheck -D nitpicky=0 -D plot_gallery=0 -D exclude_patterns="cited.rst,whats_new.rst,configure_git.rst,_includes,changes/devel" -d _build/doctrees . _build/linkcheck
-
-linkcheck-grep:
-	@! grep -h "^.*:.*: \[\(\(local\)\|\(broken\)\)\]" _build/linkcheck/output.txt
+	@$(SPHINXBUILD) -b linkcheck -D nitpicky=0 -q -D plot_gallery=0 -D exclude_patterns="cited.rst,whats_new.rst,configure_git.rst,_includes,changes/devel" -d _build/doctrees . _build/linkcheck
 
 doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest

doc/_templates/sidebar-quicklinks.html

@@ -7,6 +7,7 @@ <h5 class="card-header font-weight-bold">Version {{ release }}</h5>
             <li><a href="{{ pathto('help/index.html', 1) }}"><i class="fas fa-circle-question fa-fw"></i> Get help</a></li>
             <li><a href="{{ pathto('documentation/cite.html', 1) }}"><i class="fas fa-quote-left fa-fw"></i> Cite</a></li>
             <li><a href="{{ pathto('development/contributing.html', 1) }}"><i class="fas fa-code-branch fa-fw"></i> Contribute</a></li>
+            <li><a href="{{ pathto('credit.html', 1) }}"><i class="fas fa-hands-clapping fa-fw"></i> Contributors</a></li>
         </ul>
     </div>
 </div>

doc/changes/devel/12774.other.rst

@@ -0,0 +1,2 @@
+Code contributions are now measured using PRs and reported on the :ref:`contributors`
+page, by `Eric Larson`_.

doc/conf.py

@@ -51,6 +51,7 @@
 sys.path.append(str(curpath / "sphinxext"))
 
 from mne_doc_utils import report_scraper, reset_warnings  # noqa: E402
+from update_credit_rst import generate_credit_rst  # noqa: E402
 
 # -- Project information -----------------------------------------------------
 
@@ -616,6 +617,7 @@ def append_attr_meth_examples(app, what, name, obj, options, lines):
     "https://doi.org/10.1073/",  # pnas.org
     "https://doi.org/10.1093/",  # academic.oup.com/sleep/
     "https://doi.org/10.1098/",  # royalsocietypublishing.org
+    "https://doi.org/10.1101/",  # www.biorxiv.org
     "https://doi.org/10.1111/",  # onlinelibrary.wiley.com/doi/10.1111/psyp
     "https://doi.org/10.1126/",  # www.science.org
     "https://doi.org/10.1137/",  # epubs.siam.org
@@ -1655,6 +1657,7 @@ def setup(app):
     """Set up the Sphinx app."""
     app.connect("autodoc-process-docstring", append_attr_meth_examples)
     # High prio, will happen before SG
+    app.connect("builder-inited", generate_credit_rst, priority=10)
     app.connect("builder-inited", report_scraper.set_dirs, priority=20)
     app.connect("build-finished", make_gallery_redirects)
     app.connect("build-finished", make_api_redirects)

doc/credit.rst

@@ -0,0 +1,12 @@
+:orphan:
+
+.. _contributors:
+
+============
+Contributors
+============
+
+There are many different ways to contribute to MNE-Python! So far we only list
+code contributions below, but plan to add other metrics in the future.
+
+.. include:: ./code_credit.inc

doc/sphinxext/prs/12779.json

@@ -0,0 +1,19 @@
+{
+  "merge_commit_sha": "b8b168088cb474f27833f5f9db9d60abe00dca83",
+  "authors": [
+    {
+      "n": "Eric Larson",
+      "e": "[email protected]"
+    }
+  ],
+  "changes": {
+    "doc/sphinxext/prs/1.json": {
+      "a": 15,
+      "d": 0
+    },
+    "doc/sphinxext/prs/3732.json": {
+      "a": 15,
+      "d": 0
+    }
+  }
+}