ENH: Document relevant steps

[larsoner]

Before merging …

• Changelog has been updated (docs/source/changes.md)

Closes #862

Examples:

(I didn't realize use_maxwell_filter had a direct impact on the CSP step but it does because we pick mag there if it's used!)

Draft because I need to parse a few functions for config defs but that's a tiny detail -- the general idea and code is otherwise reviewable.

[larsoner]

Okay it was easier than I thought to parse the helper functions, ready for review/merge from my end @hoechenberger
!

[larsoner]

Also with this in place we should maybe rethink some of our categorization, for example eog_channels is only used for artifact detection:

Maybe it should live in the artifacts section.

[hoechenberger]

I will take a look at this shortly

Thanks for your effort, Eric

[hoechenberger]

I haven't tried this, but I'd prefer to use "info" instead of "success"

Suggested change

	<details class="success">
	<details class="info">

[larsoner]

I chose something other than info because that seemed to get a bit lost with the many other info blocks in our docs IIRC. Any others in here you like?

https://squidfunk.github.io/mkdocs-material/reference/admonitions/#collapsible-blocks

[larsoner]

Like these:

$ git grep "[!?+]\+ info" mne_bids_pipeline/_config.py | wc -l
      26

So I wanted to differentiate / standardize using something else. Looks like note isn't used so I'll try that?

[hoechenberger]

We can also add our own admonitions (what a word … I'll never remember it correctly!)

https://squidfunk.github.io/mkdocs-material/reference/admonitions/?h=ad#custom-admonitions

[larsoner]

Sure that would work, but we'd have to pick a color and icon. Maybe ✅ or 📋 icon? Actually abstract standard type (which we don't use anywhere) already uses the clipboard icon so that could be nice.

And maybe all the Good practice / advice that are currently info should be changed to tip?

[hoechenberger]

Sure that would work, but we'd have to pick a color and icon. Maybe ✅ or 📋 icon? Actually abstract standard type (which we don't use anywhere) already uses the clipboard icon so that could be nice.

I would also suggest to use the current "Abstract" icon – not a custom unicode one.

But really it's something we can also adjust at any later time, it's not a blocker for me right now!

[larsoner]

Okay I pushed with abstract, feel free to mark for merge-when-green if you're happy @hoechenberger !