DOC: Add detail to make_watershed_bem volume parameter (#13658)

Author: scott-huberty

doc/_includes/bem_model.rst

@@ -17,7 +17,7 @@ Using the watershed algorithm
 
 The watershed algorithm [Segonne *et al.*,
 2004] is part of the FreeSurfer software.
-The name of the program is ``mri_watershed``.
+The name of the program is mri_watershed_.
 Its use in the MNE environment is facilitated by the script
 :ref:`mne watershed_bem`.
 

doc/links.inc

@@ -72,6 +72,8 @@
 .. _python: http://www.python.org
 .. _Brain Imaging Data Structure: https://bids.neuroimaging.io/
 .. _SPEC0: https://scientific-python.org/specs/spec-0000
+.. _mri_watershed: https://surfer.nmr.mgh.harvard.edu/fswiki/mri_watershed
+.. _recon-all: https://surfer.nmr.mgh.harvard.edu/fswiki/recon-all
 
 .. python packages
 

mne/bem.py

@@ -1177,7 +1177,14 @@ def make_watershed_bem(
     %(subjects_dir)s
     %(overwrite)s
     volume : str
-        Defaults to T1.
+        The name of the MRI volume (without file extension) that
+        will be used as input to mri_watershed_. The volume is expected to
+        be full-head (non-skull-stripped), as the watershed algorithm relies on tissue
+        intensity gradients to estimate the inner skull, outer skull, and
+        outer skin surfaces. Defaults to ``"T1"``, corresponding to
+        ``$SUBJECTS_DIR/$SUBJECT/mri/T1.mgz`` in a typical FreeSurfer subject directory.
+        This volume is typically produced by the recon-all_ pipeline after the intensity
+        normalization step.
     atlas : bool
         Specify the ``--atlas option`` for ``mri_watershed``.
     gcaatlas : bool

tutorials/forward/50_background_freesurfer_mne.py

@@ -38,7 +38,7 @@
 # Let's start out by looking at the ``sample`` subject MRI. Following standard
 # FreeSurfer convention, we look at :file:`T1.mgz`, which gets created from the
 # original MRI :file:`sample/mri/orig/001.mgz` when you run the FreeSurfer
-# command `recon-all <https://surfer.nmr.mgh.harvard.edu/fswiki/recon-all>`_.
+# command recon-all_.
 # Here we use :mod:`nibabel` to load the T1 image, and the resulting object's
 # :meth:`~nibabel.spatialimages.SpatialImage.orthoview` method to view it.