RFC: doc/ folder reorg #11691
Description
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.