Fmriprep: Pare down top-level table-of-contents

[effigies]

Right now the top-level ToC is:

• Installation
• Usage Notes
• Running fMRIPrep via Docker containers
• Running fMRIPrep via Singularity containers
• Processing pipeline details
• Susceptibility Distortion Correction (SDC)
• Outputs of fMRIPrep
• Defining standard and nonstandard spaces where data will be resampled
• FAQ, Tips, and Tricks
• Contributing to FMRIPREP
• Citing fMRIPrep
• API
• What’s new

This is a lot to look through, and a pretty serious mixing of broad categories and specific issues. This conversation began in #1802, which was an attempt to deal with a rash of permissions issues faced by Singularity users, mostly related to TemplateFlow. In https://github.com/poldracklab/fmriprep/pull/1802#issuecomment-538131273, it was decided to defer another round of reorganization until today.

I would propose the following top-level structure:

• Installing and Running
• Processing Pipeline Details
• Inputs, Outputs and Templates
• Contributing
• Citing
• FAQ
• API

Specifically, in the previous issue I proposed the following:

• Installing and Running
  
  
  
  • Installation (subpage)
  
  
  • pip install fmriprep
  
  
  • pip install fmriprep-docker
  
  
  • docker pull
  
  
  • docker build (might just link out to contributors)
  
  
  • Fetch singularity (I guess from docker hub)
  
  
  • Build singularity (singularity build and docker2singularity)
  
  
  • Running fMRIPrep (subpage - mostly just the current usage notes)
  
  
  • Running fMRIPrep via Docker containers (subpage)
  
  
  • Running fMRIPrep via Singularity containers (subpage)
  
  
• Processing pipeline details
• ...

I can flesh this out further in comments, but I want to start this conversation now.

[effigies]

A full ToC:

• Installing and Running
  
  
  
  • Installation (subpage)
  
  
  • pip install fmriprep
  
  
  • pip install fmriprep-docker
  
  
  • docker pull
  
  
  • docker build (might just link out to contributors)
  
  
  • Fetch singularity (I guess from docker hub)
  
  
  • Build singularity (singularity build and docker2singularity)
  
  
  • Running fMRIPrep (subpage - mostly just the current usage notes)
  
  
  • Running fMRIPrep via Docker containers (subpage)
  
  
  • Running fMRIPrep via Singularity containers (subpage)
  
  
• Processing pipeline details
  
  
  
  • Anatomical preprocessing
  
  
  • BOLD preprocessing
  
  
  • Susceptibility distortion correction
  
  
• Inputs, Outputs and Templates
  
  
  
  • Inputs: BIDS, Pre-run FreeSurfer, touch on TemplateFlow (subpage)
  
  
  • Outputs (subpage)
  
  
  • Spaces and Templates (subpage)
  
  
• Contributing
• Citing
• FAQ
• API

[jdkent]

I agree with this overall structure. :+1:

Side Note:
I think API has a lot of great information for users (the doc strings give good conceptual overviews of the workflows), but I'm afraid most will not think to look there (API connotes highly technical to me).

The solution I see would be to reference the API in other sections where appropriate to guide people to know how a workflow is constructed.