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, RFC: better visibility for "algorithms" pages #6792

Closed drammock closed 5 years ago

drammock commented 5 years ago

6767 yielded a few documentation pages that are live, but are not very findable; they are located in doc/overview/algorithms. Most are very good; a couple of them may need some cleanup / fleshing out. Find a way to make them more discoverable. Possibilities:

  1. an algorithms TOC page that is linked from docs/overview/index.rst
  2. combine the algorithms pages into one page that is linked from docs/overview/index.rst
  3. merge the algorithms with the "implementation details" content
  4. other ideas ???

cc @jasmainak

jasmainak commented 5 years ago

I don't quite like "implementation details" because it gives the impression that they are not important. Something I've realized after discussions with @mshamalainen is that we miss the mathematical details in MNE-Python.

Scikit-learn does a good job in their "user guide" and so does the MNE-C manual. But MNE-Python really skims over it. I shouldn't have to go read 5 papers to figure out what is the one equation of beamformers that is implemented. Scientific software does have an educational role as well

drammock commented 5 years ago

looks like in #6767 we also lost the io page, @agramfort might want to restore it?

larsoner commented 5 years ago

Yeah we should probably restore it for release

larsoner commented 5 years ago

There was a lot of overlap between the old pages but I didn't mean to remove the content. So yes restore plus deduplicate is the way to go. @drammock feel free to go for it on Monday, we should be able to release Tues or Wed hopefully