[DOC] update doc

.github/workflows/test_doc.yml

@@ -0,0 +1,40 @@
+name: test examples
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
+on:
+    push:
+        branches: [ "master" ]
+    pull_request:
+        branches: [ "master" ]
+
+    schedule:
+        - cron: 0 0 1 * *
+
+    # Allows you to run this workflow manually from the Actions tab
+    workflow_dispatch:
+
+jobs:
+    test_examples:
+        runs-on: ubuntu-22.04
+
+        steps:
+        - uses: actions/checkout@v3
+
+        - name: Set up Python
+          uses: actions/setup-python@v4
+          with:
+            python-version: '3.11'
+
+        - name: Install neurodocker
+          run: python -m pip install --editable .
+
+        - name: test common uses
+          run: bash < docs/common_uses/conda_multiple_env.txt
+
+        - name: "test nipype_tuto: failure expected"
+          run: bash < docs/examples/nipype_tuto.txt
+          # do not fail the workflow if the example fails
+          continue-on-error: true

docs/common_uses/conda_multiple_env.txt

@@ -0,0 +1,17 @@
+neurodocker generate docker \
+    --pkg-manager apt \
+    --base-image debian:bullseye-slim \
+    --miniconda \
+        version=latest \
+        env_name=envA \
+        env_exists=false \
+        conda_install=pandas \
+    --miniconda \
+        version=latest \
+        installed=true \
+        env_name=envB \
+        env_exists=false \
+        conda_install=scipy \
+> multi-conda-env.Dockerfile
+
+docker build --tag multi-conda-env --file multi-conda-env.Dockerfile .

docs/examples/nipype_tuto.txt

@@ -0,0 +1,38 @@
+neurodocker generate docker \
+        --pkg-manager apt \
+        --base-image debian:bullseye-slim \
+        --yes \
+        --ants version=2.4.3 \
+        --fsl version=6.0.7.1 \
+        --convert3d version=1.0.0 \
+        --install gcc g++ graphviz tree git-annex vim emacs-nox nano less ncdu tig octave netbase \
+        --miniconda \
+                version=latest \
+                mamba=true \
+                conda_install="python=3.11 nipype pybids=0.16.3 pytest jupyterlab jupyter_contrib_nbextensions traits scikit-image seaborn nbformat nb_conda" \
+                pip_install="nilearn=0.10.1 datalad[full] nipy duecredit nbval" \
+        --run 'jupyter nbextension enable exercise2/main && jupyter nbextension enable spellchecker/main' \
+        --run 'mkdir /data && chmod 777 /data && chmod a+s /data' \
+        --run 'mkdir /output && chmod 777 /output && chmod a+s /output' \
+        --spm12 version=r7771 \
+        --user neuro \
+        --run-bash 'cd /data
+                && datalad install -r ///workshops/nih-2017/ds000114
+                && cd ds000114
+                && datalad update -r
+                && datalad get -r sub-01/ses-test/anat sub-01/ses-test/func/*fingerfootlips*' \
+        --run 'curl -fL https://files.osf.io/v1/resources/fvuh8/providers/osfstorage/580705089ad5a101f17944a9 -o /data/ds000114/derivatives/fmriprep/mni_icbm152_nlin_asym_09c.tar.gz
+                && tar xf /data/ds000114/derivatives/fmriprep/mni_icbm152_nlin_asym_09c.tar.gz -C /data/ds000114/derivatives/fmriprep/.
+                && rm /data/ds000114/derivatives/fmriprep/mni_icbm152_nlin_asym_09c.tar.gz
+                && find /data/ds000114/derivatives/fmriprep/mni_icbm152_nlin_asym_09c -type f -not -name ?mm_T1.nii.gz -not -name ?mm_brainmask.nii.gz -not -name ?mm_tpm*.nii.gz -delete' \
+        --copy . "/home/neuro/nipype_tutorial" \
+        --user root \
+        --run 'chown -R neuro /home/neuro/nipype_tutorial' \
+        --run 'rm -rf /opt/conda/pkgs/*' \
+        --user neuro \
+        --run 'mkdir -p ~/.jupyter && echo c.NotebookApp.ip = \"0.0.0.0\" > ~/.jupyter/jupyter_notebook_config.py' \
+        --workdir /home/neuro/nipype_tutorial \
+        --entrypoint jupyter-notebook \
+> nipype-tutorial.Dockerfile
+
+docker build --tag nipype-tutorial --file nipype-tutorial.Dockerfile .

docs/user_guide/common_uses.rst

@@ -31,7 +31,7 @@ This example demonstrates how to build and run an image with Jupyter Notebook.
 
     neurodocker generate docker \
         --pkg-manager apt \
-        --base-image debian:buster-slim \
+        --base-image debian:bullseye-slim \
         --miniconda \
             version=latest \
             conda_install="matplotlib notebook numpy pandas seaborn" \
@@ -44,7 +44,9 @@ This example demonstrates how to build and run an image with Jupyter Notebook.
 
     # Run the image. The current directory is mounted to the working directory of the
     # Docker image, so our notebooks are saved to the current directory.
-    docker run --rm -it --publish 8888:8888 --volume $(pwd):/work notebook \
+    docker run --rm -it \
+        --publish 8888:8888 \
+        --volume $(pwd):/work notebook \
         jupyter-notebook --no-browser --ip 0.0.0.0
 
 
@@ -53,25 +55,7 @@ Multiple Conda Environments
 
 This example demonstrates how to create a Docker image with multiple conda environments.
 
-.. code-block:: bash
-
-    neurodocker generate docker \
-        --pkg-manager apt \
-        --base-image debian:buster-slim \
-        --miniconda \
-            version=latest \
-            env_name=envA \
-            env_exists=false \
-            conda_install=pandas \
-        --miniconda \
-            version=latest \
-            installed=true \
-            env_name=envB \
-            env_exists=false \
-            conda_install=scipy \
-    > multi-conda-env.Dockerfile
-
-    docker build --tag multi-conda-env --file multi-conda-env.Dockerfile .
+.. literalinclude:: common_uses/conda_multiple_env.txt
 
 One can use the image in the following way:
 

docs/user_guide/examples.rst

@@ -48,13 +48,19 @@ Docker
 
     neurodocker generate docker \
         --pkg-manager apt \
-        --base-image debian:buster-slim \
-        --fsl version=6.0.4 \
-    > fsl604.Dockerfile
+        --base-image debian:bullseye-slim \
+        --fsl version=6.0.7.1 \
+    > fsl6071.Dockerfile
+
+    docker build --tag fsl:6.0.7.1 --file fsl6071.Dockerfile .
 
-# This will ask the following question interactively: FSL is non-free. If you are considering commercial use of FSL, please consult the relevant license(s). Proceed? [y/N]
+This will ask the following question interactively:
 
-# If you are using neurodocker non-interactively, this problem can be avoided using:
+.. code-block:: bash
+
+    FSL is non-free. If you are considering commercial use of FSL, please consult the relevant license(s). Proceed? [y/N]
+
+If you are using neurodocker non-interactively, this problem can be avoided using:
 
 .. code-block:: bash
 
@@ -82,7 +88,7 @@ Docker
 
     neurodocker generate docker \
         --pkg-manager yum \
-        --base-image fedora:35 \
+        --base-image fedora:36 \
         --afni method=binaries version=latest \
     > afni-binaries.Dockerfile
 
@@ -95,25 +101,30 @@ This does not install AFNI's R packages. To install relevant R things, use the f
 
     neurodocker generate docker \
         --pkg-manager yum \
-        --base-image fedora:35 \
+        --base-image fedora:36 \
         --afni method=binaries version=latest install_r_pkgs=true \
     > afni-binaries-r.Dockerfile
 
     docker build --tag afni:latest-with-r --file afni-binaries-r.Dockerfile .
 
+.. todo::
 
-One can also build AFNI from source. The code below builds the current master branch.
-Beware that this is AFNI's bleeding edge!
+    Building AFNI from source is currently failing on most tested distributions.
 
-.. code-block:: bash
+.. https://github.com/ReproNim/neurodocker/blob/test_docker_build/docs/README.md#afni
 
-    neurodocker generate docker \
-        --pkg-manager yum \
-        --base-image fedora:35 \
-        --afni method=source version=master \
-    > afni-source.Dockerfile
+.. One can also build AFNI from source. The code below builds the current master branch.
+.. Beware that this is AFNI's bleeding edge!
+
+.. .. code-block:: bash
+
+..     neurodocker generate docker \
+..         --pkg-manager yum \
+..         --base-image fedora:36 \
+..         --afni method=source version=master \
+..     > afni-source.Dockerfile
 
-    docker build --tag afni:master --file afni-source.Dockerfile .
+..     docker build --tag afni:master --file afni-source.Dockerfile .
 
 FreeSurfer
 ----------
@@ -124,19 +135,25 @@ FreeSurfer
 Docker
 ~~~~~~
 
-The FreeSurfer installation is several gigabytes in size, but sometimes, users just
-the pieces for :code:`recon-all`. For this reason, Neurodocker provides a FreeSurfer
-minified for :code:`recon-all`.
-
 .. code-block:: bash
 
     neurodocker generate docker \
         --pkg-manager apt \
-        --base-image debian:buster-slim \
-        --freesurfer version=7.1.1-min \
-    > freesurfer7-min.Dockerfile
+        --base-image debian:bullseye-slim \
+        --freesurfer version=7.4.1 \
+    > freesurfer741.Dockerfile
+
+    docker build --tag freesurfer:7.4.1 --file freesurfer741.Dockerfile .
 
-    docker build --tag freesurfer:7.1.1-min --file freesurfer7-min.Dockerfile .
+.. todo::
+
+    The minified version on Freesurfer currently fails to build on all tested distributions.
+
+.. https://github.com/ReproNim/neurodocker/blob/test_docker_build/docs/README.md#freesurfer
+
+.. The FreeSurfer installation is several gigabytes in size, but sometimes, users just
+.. the pieces for :code:`recon-all`. For this reason, Neurodocker provides a FreeSurfer
+.. minified for :code:`recon-all`.
 
 ANTS
 ----
@@ -145,51 +162,59 @@ ANTS
 
     neurodocker generate docker \
         --pkg-manager apt \
-        --base-image debian:buster-slim \
-        --ants version=2.3.4 \
+        --base-image debian:bullseye-slim \
+        --ants version=2.4.3 \
     > ants-234.Dockerfile
 
-    docker build --tag ants:2.3.4 --file ants-234.Dockerfile .
+    docker build --tag ants:2.4.3 --file ants-243.Dockerfile .
 
+.. note::
+
+    Building docker images of ANTS from source fails on most tested distributions.
 
+.. https://github.com/ReproNim/neurodocker/blob/test_docker_build/docs/README.md#ants
 
 CAT12
 -----
 
-CAT12 requires the MCR in the correction version. Miniconda and nipype is optional but recommended to use CAT12 from NiPype.
+CAT12 requires the MCR in the correction version.
+Miniconda and nipype is optional but recommended to use CAT12 from NiPype.
 
 .. code-block:: bash
 
     neurodocker generate docker \
-        --base-image ubuntu:16.04 \
+        --base-image ubuntu:22.04 \
         --pkg-manager apt \
         --mcr 2017b \
-        --cat12 version=r1933_R2017b \
+        --cat12 version=r2166_R2017b \
         --miniconda \
          version=latest \
-         conda_install='python=3.8 traits nipype numpy scipy h5py scikit-image' \
-    > cat12-r1933_R2017b.Dockerfile
+         conda_install='python=3.11 traits nipype numpy scipy h5py scikit-image' \
+    > cat12-r2166_R2017b.Dockerfile
 
-    docker build --tag cat12:r1933_R2017b --file cat12-r1933_R2017b.Dockerfile .
+    docker build --tag cat12:r2166_R2017b --file cat12-r2166_R2017b.Dockerfile .
 
 SPM
 ---
 
-.. note::
-
-    Due to the version of the Matlab Compiler Runtime used, SPM12 should be used with
-    a Debian Stretch base image.
+..     Due to the version of the Matlab Compiler Runtime used,
+..     SPM12 should be used with a Debian Stretch base image.
 
 .. code-block:: bash
 
     neurodocker generate docker \
         --pkg-manager apt \
-        --base-image debian:stretch-slim \
+        --base-image centos:7 \
         --spm12 version=r7771 \
     > spm12-r7771.Dockerfile
 
     docker build --tag spm12:r7771 --file spm12-r7771.Dockerfile .
 
+.. note::
+
+    Building docker images of SPM12 from source fails on most tested distributions.
+
+.. https://github.com/ReproNim/neurodocker/blob/test_docker_build/docs/README.md#spm12
 
 Miniconda
 ---------
@@ -200,7 +225,7 @@ Docker with new :code:`conda` environment, python packages installed with :code:
 
     neurodocker generate docker \
         --pkg-manager apt \
-        --base-image debian:buster-slim \
+        --base-image debian:bullseye-slim \
         --miniconda \
             version=latest \
             env_name=env_scipy \
@@ -212,53 +237,12 @@ Docker with new :code:`conda` environment, python packages installed with :code:
     docker build --tag conda-env --file conda-env.Dockerfile .
 
 
-Nipype tutorial
----------------
+.. Nipype tutorial
+.. ---------------
 
-.. _nipype_tutorial_docker:
+.. .. _nipype_tutorial_docker:
 
 Docker
 ~~~~~~
 
-.. code-block:: bash
-
-    neurodocker generate docker \
-    --pkg-manager apt \
-    --base-image neurodebian:stretch-non-free \
-    --arg DEBIAN_FRONTEND=noninteractive \
-    --install convert3d ants fsl gcc g++ graphviz tree \
-            git-annex-standalone vim emacs-nox nano less ncdu \
-            tig git-annex-remote-rclone octave netbase \
-    --spm12 version=r7771 \
-    --miniconda \
-    version=latest \
-    conda_install="python=3.8 pytest jupyter jupyterlab jupyter_contrib_nbextensions
-                    traits pandas matplotlib scikit-learn scikit-image seaborn nbformat
-                    nb_conda" \
-    pip_install="https://github.com/nipy/nipype/tarball/master
-                    https://github.com/INCF/pybids/tarball/master
-                    nilearn datalad[full] nipy duecredit nbval" \
-    --run 'jupyter nbextension enable exercise2/main && jupyter nbextension enable spellchecker/main' \
-    --run 'mkdir /data && chmod 777 /data && chmod a+s /data' \
-    --run 'mkdir /output && chmod 777 /output && chmod a+s /output' \
-    --user neuro \
-    --run-bash 'cd /data
-    && datalad install -r ///workshops/nih-2017/ds000114
-    && cd ds000114
-    && datalad update -r
-    && datalad get -r sub-01/ses-test/anat sub-01/ses-test/func/*fingerfootlips*' \
-    --run 'curl -fL https://files.osf.io/v1/resources/fvuh8/providers/osfstorage/580705089ad5a101f17944a9 -o /data/ds000114/derivatives/fmriprep/mni_icbm152_nlin_asym_09c.tar.gz
-    && tar xf /data/ds000114/derivatives/fmriprep/mni_icbm152_nlin_asym_09c.tar.gz -C /data/ds000114/derivatives/fmriprep/.
-    && rm /data/ds000114/derivatives/fmriprep/mni_icbm152_nlin_asym_09c.tar.gz
-    && find /data/ds000114/derivatives/fmriprep/mni_icbm152_nlin_asym_09c -type f -not -name ?mm_T1.nii.gz -not -name ?mm_brainmask.nii.gz -not -name ?mm_tpm*.nii.gz -delete' \
-    --copy . "/home/neuro/nipype_tutorial" \
-    --user root \
-    --run 'chown -R neuro /home/neuro/nipype_tutorial' \
-    --run 'rm -rf /opt/conda/pkgs/*' \
-    --user neuro \
-    --run 'mkdir -p ~/.jupyter && echo c.NotebookApp.ip = \"0.0.0.0\" > ~/.jupyter/jupyter_notebook_config.py' \
-    --workdir /home/neuro/nipype_tutorial \
-    --entrypoint jupyter-notebook \
-    > nipype-tutorial.Dockerfile
-
-    docker build --tag nipype-tutorial .
+.. literalinclude:: examples/nipype_tuto.txt