search

mne-tools / mne-python

MNE: Magnetoencephalography (MEG) and Electroencephalography (EEG) in Python
https://mne.tools
BSD 3-Clause "New" or "Revised" License
2.69k stars 1.31k forks source link

DOC: improve docs and add more tutorials #595

Closed dengemann closed 10 years ago

dengemann commented 11 years ago

Very general issue, I just quickly drop a few thoughts here to stimulate some discussion / remind us of a few things. I think as we grow in terms of users and developers we should have more resources / very good reasons to write more extensive tutorials. We already started doing so e.g. in the last contributions to our stats module. Still I feel there are some non-trivial parts of our code which still aren't extremely well documented, e.g. - arbitrary example -- the LCMV beamformer docs / examples give you no real idea what is what unless you read the related references / look it up elsewhere (what is the data covariance and how to chose its window, what kind of source estimate is returned, what's its regular value range, etc.) It would be nice to improve some of our examples as we proceed / on the fly, e.g., make them more verbose, explain options, name good practices, add references, etc. Actually it would be cool to come up with some approximative taxonomy we can use to design STC docs (value type: source estimate VS statistic, value range: signed | unsigned | F-value, ... etc.) more systematically. This could also go in a central source localization tutorial that comments and links to the different examples we have. Anyways, just throwing thoughts.

mluessi commented 11 years ago

I agree, it would be good to have more extensive tutorials and to improve the examples. I think we should look into converting all the tutorials to IPython notebooks and then figure out a way to have sphinx execute them and convert to static html when the doc is built (similar to nbviewer). This would make it much easier to write tutorials and it makes sure they actually work. I can look into this if there is interest.

dengemann commented 11 years ago

@mluessi that would be cool! Is there actually a way to automagically convert a regular script into an IPython notebook? ^^

agramfort commented 11 years ago

look maybe at nbconvert but I am a bit afraid to add dependency on this very recent piece of code.

dengemann commented 11 years ago

We could use that offline to get the bulk of our examples converted ...

mluessi commented 11 years ago

Yes, nbconvert would just be needed to build the doc. But I agree, we don't want to depend on code that is very new. The good thing is that IPython won't disappear.. so something similar to nbconvert should always be available in the foreseeable future.

dengemann commented 10 years ago

Closing for now.