RFC: doc/ folder reorg

[drammock]

The organization of files in our doc/ folder is out of control; every time I need to edit a page in our docs it is a challenge to find the correct .rst source file. Below (hidden under "details") I lay out a proposal to have subfolders within doc/ mirror the top-level sections of our site. Given that there are a few outstanding issues with doc content and organization:

• install documentation cleanup #10707
• DOC: Add resources for Python, terminal use etc. #11370
• Update contributing guide #11609

...I feel like now is the time to tackle this.

Note that a couple years ago there was some discussion of reorganizing the website pages (I think around the time of #8757 or #9292, when the API pages were split up?) about "not breaking people's browser bookmarks" (I think @agramfort was the one who raised this objection?). Nowadays we already track a bunch of custom redirects in conf.py so IMO that objection is not nearly as strong today as it was then.

.
├── auto_examples
│   └── ... 16 items
│
├── auto_tutorials
│   └── ... 20 items
│
├── bibliography.rst               →  (orphan) linked from overview/cite.rst
│
├── _build
│   └── ... 3 items
│
├── changes
│   └── ... 31 items
│
├── cited.rst                      →  move to `doc/documentation/`
├── conf.py
├── conftest.py
├── connectivity.rst               →  move to `doc/api/`
├── contributing.html              →  (redirect) to install/contributing.rst
├── covariance.rst                 →  move to `doc/api/`
├── creating_from_arrays.rst       →  move to `doc/api/`
├── datasets.rst                   →  move to `doc/api/`
├── decoding.rst                   →  move to `doc/api/`
├── documentation.html             →  (redirect) to overview/index.rst
├── events.rst                     →  move to `doc/api/`
├── export.rst                     →  move to `doc/api/`
├── file_io.rst                    →  move to `doc/api/`
├── forward.rst                    →  move to `doc/api/`
├── funding.rst                    →  (orphan) linked from homepage
│
├── generated
│   └── ... 2491 items
│
├── getting_started.html           →  redirect to install/index.rst (1 of 2)
├── glossary.rst                   →  move to `doc/documentation/`
│
├── _includes
│   └── ... 13 items               →  these can be left alone for now, but worth revisiting
│                                     which ones are still needed (or only needed in one place,
│                                     hence no longer necessary to abstract into an `.. include::`
│                                     directive)
│
├── index.rst                      →  (main homepage)
│
├── install
│   ├── advanced.rst               →  ok
│   ├── check_installation.rst     →  ok
│   ├── contributing.rst           →  move to `doc/development/`
│   ├── freesurfer.rst             →  ok
│   ├── index.rst                  →  ok
│   ├── installers.rst             →  ok
│   ├── manual_install_python.rst  →  (orphan, cruft?) linked from `install/contributing`,
│   │                                 `install/manual_install`, and `overview/get_help`. Maybe
│   │                                 cruft because it recommends Anaconda (instead of mambaforge)
│   │
│   ├── manual_install.rst         →  ok
│   ├── mne_c.rst                  →  ok
│   ├── mne_tools_suite.rst        →  ok
│   └── updating.rst               →  ok
│
├── install_mne_python.html        →  (redirect) to install/index.rst (2 of 2)
├── inverse.rst                    →  move to `doc/api/`
├── links.inc
├── logging.rst                    →  move to `doc/api/`
├── Makefile
├── martinos.rst                   →  (orphan) not linked from anywhere (is this still valid/needed?)
├── mne_cpp.rst                    →  (orphan) linked from `doc/install/mne_tools_suite.rst` (still needed?)
├── most_used_classes.rst          →  move to `doc/api/`
├── mri.rst                        →  move to `doc/api/`
│
├── overview
│   ├── cite.rst                   →  move to `doc/documentation/` (maybe as `how-to-cite.rst` to differentiate from `cited.rst`?)
│   ├── cookbook.rst               →  (split?) move to `doc/documentation/`
│   ├── datasets_index.rst         →  move to `doc/documentation/datasets.rst`
│   ├── design_philosophy.rst      →  (cruft? split?) move to `doc/documentation/`
│   ├── development.rst            →  move to `doc/development/index.rst`
│   ├── faq.rst                    →  (needs overhaul) move to `doc/help/`
│   ├── get_help.rst               →  move to `doc/help/index.rst`
│   ├── governance.rst             →  move to `doc/development/`
│   ├── images
│   │   ├── Digitizer-example.png  →  (cruft)
│   │   └── flow_diagram.svg       →  move to `doc/_static/`
│   ├── implementation.rst         →  (split?) move to `doc/documentation/`
│   ├── index.rst                  →  move to `doc/documentation/index.rst`
│   ├── learn_python.rst           →  move to `doc/help/`
│   ├── matlab.rst                 →  (cruft?) move to `doc/documentation/`
│   ├── migrating.rst              →  move to `doc/help/migrating.rst`
│   ├── people.rst                 →  (orphan) linked from `doc/overview/governance.rst`
│   └── roadmap.rst                →  move to `doc/development/`
│
├── preprocessing.rst              →  move to `doc/api/`
├── python_reference.rst           →  move to `doc/api/`
├── reading_raw_data.rst           →  move to `doc/api/`
├── realtime.rst                   →  move to `doc/api/`
├── references.bib
├── report.rst                     →  move to `doc/api/`
├── sensor_space.rst               →  move to `doc/api/`
├── simulation.rst                 →  move to `doc/api/`
├── source_space.rst               →  move to `doc/api/`
│
├── sphinxext
│   └── ... 8 items
│
├── _static
│   └── ... 16 items
│
├── statistics.rst                 →  move to `doc/api/`
│
├── _templates
│   └── ... 5 items
│
├── time_frequency.rst             →  move to `doc/api/`
├── visualization.rst              →  move to `doc/api/`
└── whats_new.rst                  →  move to `doc/development/`

Eager to hear what @mne-tools/mne-python-steering-committee thinks about this.

[agramfort]

sounds like a wise idea !

…

Message ID: ***@***.***>

[larsoner]

I feel the same pain and having the organization mirror the docs would be great!

[sappelhoff]

I would also find such a re-organization beneficial!

[alexrockhill]

+1

[hoechenberger]

every time I need to edit a page in our docs it is a challenge to find the correct .rst source file

Interesting 🤔 The way I usually do it is that I look at the URL in the browser, copy the filename and then in VS Code I use Cmd-P and paste the base of the filename, which usually takes me right to the relevant RST file.

That said, I like organization, so +1 from my side on this endeavor 👍

[britta-wstnr]

Sounds good to me! +1

[mmagnuski]

+1 from me too!