search

mne-tools / mne-bids-pipeline

Automatically process entire electrophysiological datasets using MNE-Python.
https://mne.tools/mne-bids-pipeline/
BSD 3-Clause "New" or "Revised" License
133 stars 65 forks source link

DOC: Automatically document settings #863

Closed larsoner closed 4 months ago

larsoner commented 4 months ago

This PR automatically adds configuration options from _config.py to docs/source/settings/. It's a first step toward #862. To accomplish this, I wrote code to parse header levels # , ##, ### and map those onto our current hierarchy. I made a few opinionated choices:

  1. Make a new Execution section that has stuff like n_jobs. It seems useful to separate those from stuff like bids_root which are more dataset-specific and actually affect what gets generated as opposed to how it gets generated on machines / jobs etc..

    image

  2. Chose the website docs as the source of truth for parameter order. This means the _config.py diff is bigger, but the .md diffs are smaller.

  3. Chose to add the tags to the _config.py. This was a bit of a toss-up for me -- if it is not useful there I can easily just move those to a dict in gen_settings.py.

For now I have left the generated .md files in source control but this is just to facilitate review to see how the docs have changed. Once people are happy I will rm and add to .gitignore.

Link to rendered doc: https://output.circle-artifacts.com/output/job/0a5e0fe7-0af8-4717-80f5-e33f99967966/artifacts/0/site/settings/general.html

Before merging …

larsoner commented 4 months ago

Even with all the parsing code we end up with a net-negative line count in the diff +511 −689 which is nice! Ready for review/merge from my end @hoechenberger

hoechenberger commented 4 months ago

@larsoner I won't be able to thoroughly review for now; please go ahead and merge if you're happy and i'll start complaining sometime later 😁

larsoner commented 4 months ago

i'll start complaining sometime later 😁

Complaints always welcome, but even more welcome if they're in the form of a PR to improve wordings etc. :smile:

SophieHerbst commented 4 months ago

In my view, it would be helpfull to explain the memory-related arguments, and more generally the caching behavior in a dedicated page, like the basic usage

hoechenberger commented 4 months ago

In my view, it would be helpfull to explain the memory-related arguments, and more generally the caching behavior in a dedicated page, like the basic usage

i agree!!