Various updates and changes to the documentation #765

dkuegler · 2026-01-19T17:25:58Z

This PR has various changes and updates to the fastsurfer documentation.

Two example:

consistently mount/bind shared folders for singularity and docker in the same location as on the host file system (to simplify the documentation)
move the singularity example into position 1 (instead of the docker example)

Todos:

~~rebase the changes onto dev (currently on ClePol/CC_doc)~~
review and test the documentation for consistency and completeness

…dget.

Add help to building from docker archive files Clean up doc/conf.py Add list of used packages to license document in documentation Update requirements link Update Singularity doc Update PYTHONPATH is only required for direct calls to python scripts (shell scripts define the PYTHONPATH as well) Fix links to SINGULARITY.md Add FASTSURFER_VERSION as a substitution ({{ FASTSURFER_VERSION }}) Update docs to use same path inside container as outside image does not need to be pulled if docker, docker does that automatically Remove (outdated) manual edits description from recon_surf/README.md (but reference doc/overview/EDITING.md) doc fixes Fixes to the documentation. - slurm-help: does not change between different runs (on github actions) - most documentation files

improve instructions for issue submission

Copilot

Pull request overview

This PR updates FastSurfer documentation to improve consistency and clarity. The main changes include:

Standardizing mount/bind paths between Docker and Singularity to use the same locations as the host file system (using $HOME instead of mapping to different paths like /data, /output)
Reordering examples to show Singularity first, then Docker
Updating formatting and structure across documentation files

Changes:

Unified path mounting approach: Docker and Singularity now mount folders to the same path inside containers as on the host
Reordered examples: Singularity examples moved to position 1 throughout documentation
Improved documentation structure with consistent headers and formatting

Reviewed changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tools/Docker/README.md	Updated Docker examples to use `$HOME` paths consistently, fixed flag descriptions
doc/overview/SINGULARITY.md	Major restructuring with containerization explanation, updated examples
doc/overview/EXAMPLES.md	Swapped example order (Singularity first), updated paths to use `$HOME`
doc/overview/INSTALL.md	Updated references to example numbers after reordering
doc/scripts/RUN_FASTSURFER.md	Restructured flags documentation, added conditionally required section
recon_surf/README.md	Updated examples with consistent `$HOME` paths
README.md	Updated usage section with clearer flag explanations and `$HOME` paths
stools.sh	Minor comment typo fix
srun_fastsurfer.sh	Updated time limit warnings for CPU processing
Other files	Various formatting improvements, typo fixes, and structural updates

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-19T18:41:07Z

stools.sh

 #!/bin/bash

-# script for functions used by srun_fastsurfer.sh and srun_freesufer.sh
+# script for functions used by srun_fastsurfer.sh and brun_freesufer.sh


Typo in comment: "brun_freesufer.sh" should be "srun_freesurfer.sh". The script mentioned appears to be misnamed - it should match the FastSurfer naming convention.

Copilot · 2026-01-19T18:41:07Z

tools/Docker/README.md

+           -v $HOME/my_fs_license.txt:$HOME/my_fs_license.txt \
+           --rm --user $(id -u):$(id -g) my_fastsurfer:rocm \
+               --fs_license $HOME/my_fs_license.txt \
+               --t1 $HOME/my_mri_data/subjectX/t1-weighed.nii.gz \


Typo in filename: "t1-weighed.nii.gz" should be "t1-weighted.nii.gz". This appears twice in the same example (lines 157 and 176).

Copilot · 2026-01-19T18:41:07Z

tools/Docker/README.md

+	       -v $HOME/my_mri_data:$HOME/my_mri_data \
+           -v $HOME/my_fastsurfer_analysis:$HOME/my_fastsurfer_analysis \
+           -v $HOME/my_fs_license.txt:$HOME/my_fs_license.txt \
+           --rm --user $(id -u):$(id -g) my_fastsurfer:rocm \


Duplicate "--rm" flag on line 155. The --rm flag is already present on line 151, so line 155 should be removed.

Copilot · 2026-01-19T18:41:08Z

doc/overview/SINGULARITY.md

-                 -B /home/user/my_fastsurfer_analysis:/output \
-                 -B /home/user/my_fs_license_dir:/fs \
-                  /home/user/fastsurfer-gpu.sif \
+                 --no-mount home,cwd -e\


Typo in variable reference: "--no-mount home,cwd" should be "--no-mount home,cwd" on line 91, but the text description says it should match line 59 which has "--no-mount home,cwd -e". The backslash after "-e" on line 59 seems incorrect.

Suggested change

--no-mount home,cwd -e\

--no-mount home,cwd -e \

Copilot · 2026-01-19T18:41:08Z

recon_surf/README.md

-                  --sid subjectX --sd /output --3T \
-                  --t1 <path_to>/subjectX/mri/orig.mgz \
-                  --asegdkt_segfile <path_to>/subjectX/mri/aparc.DKTatlas+aseg.deep.mgz
+                  --fs_license $HOME/fs_license/license.txt \


Typo in path: "$HOME/fs_license/license.txt" on line 80 doesn't match the mounted path from line 77 which is "$HOME/my_fs_license.txt". This should be "$HOME/my_fs_license.txt" for consistency.

Suggested change

--fs_license $HOME/fs_license/license.txt \

--fs_license $HOME/my_fs_license.txt \

Copilot · 2026-01-19T18:41:08Z

recon_surf/README.md

            /fastsurfer/brun_fastsurfer.sh \
            --surf_only \
-            --subjects_list /lists/subjects_list.txt \
+            --subjects_list $HOME/subjects_lists//subjects_list.txt \


Double slash in path: "$HOME/subjects_lists//subjects_list.txt" should be "$HOME/subjects_lists/subjects_list.txt" (single slash).

Suggested change

--subjects_list $HOME/subjects_lists//subjects_list.txt \

--subjects_list $HOME/subjects_lists/subjects_list.txt \

Copilot · 2026-01-19T18:41:08Z

CONTRIBUTING.md

+16. Force push the updated feature branch to your GitHub: `git push -f origin my-new-feature`
+
+    ```bash
+    git checkout devgit pull upstream dev


Inconsistent placeholder format. Line 122 uses "$HOME/FastSurfer/data" as a path, but should use $HOME directly without the FastSurfer subdirectory for consistency with other examples, or should make clear this is just an example path structure.

Suggested change

git checkout devgit pull upstream dev

git checkout dev

git pull upstream dev

Fix the message that checked if cpu_only was run without more time bu…

2e4edfe

…dget.

dkuegler force-pushed the feature/doc-update branch from f01be1c to 10a9762 Compare January 19, 2026 18:07

dkuegler added 7 commits January 19, 2026 19:20

Clean up some formatting in several files

c058924

Unifying formatting in doc

52097a5

Streamline the Contribution page

e3c2431

improve instructions for issue submission

Update the github issue templates

a69f8ce

Fix the link to FLAGS in cc doc

7681df9

Fix doc/conf.py

8d4abcf

dkuegler force-pushed the feature/doc-update branch from 0fc9a39 to 8d4abcf Compare January 19, 2026 18:20

m-reuter requested a review from Copilot January 19, 2026 18:37

Copilot started reviewing on behalf of m-reuter January 19, 2026 18:38 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Various updates and changes to the documentation #765

Various updates and changes to the documentation #765

Uh oh!

dkuegler commented Jan 19, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

	--fs_license $HOME/fs_license/license.txt \
	--fs_license $HOME/my_fs_license.txt \

	--subjects_list $HOME/subjects_lists//subjects_list.txt \
	--subjects_list $HOME/subjects_lists/subjects_list.txt \

	git checkout devgit pull upstream dev
	git checkout dev
	git pull upstream dev

Various updates and changes to the documentation #765

Are you sure you want to change the base?

Various updates and changes to the documentation #765

Uh oh!

Conversation

dkuegler commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dkuegler commented Jan 19, 2026 •

edited

Loading