Add a tutorial section to the page (#48)

.github/scripts/fetch_external_sources.sh

@@ -8,36 +8,51 @@
 try_fetch() {
     local org=${1}
     local file=${2}
+    local outputbase=${3}
     local repo=$(echo ${file} | awk -F '/' '{print $1}')
     local repo_file=${file/${repo}/}
 
     for branch in main master; do
-      curl --fail --silent https://raw.githubusercontent.com/${org}/${repo}/${branch}/${repo_file#/} -o ${file} && break
+      curl --fail --silent https://raw.githubusercontent.com/${org}/${repo}/${branch}/${repo_file#/} -o ${outputbase}/${file} && break
     done
 }
 
-while read -r line; do
-  # Check if line is non-empty and ends on .md
-  if [ -n "${line}" ] && [[ "${line}" == *.md ]]; then
-    # If the file exists do nothing, otherwise pull it in from github
-    if ! ls "${line}" > /dev/null 2>&1; then
-      echo "${line} does not exist. Trying to fetch it from github"
-      mkdir -p  $(dirname ${line}) # make the directory for the output
-
-      # Try a few github organizations
-      for org in key4hep HEP-FCC AIDASoft iLCSoft; do
-        echo "Trying to fetch from github organization: '${org}'"
-        if try_fetch ${org} ${line}; then
-          echo "Fetched succesfully from organization '${org}'"
-          break
-        fi
-      done
-    fi
+# process one markdown file with content that potentially needs fetching from an
+# external repository
+fetch_for_file() {
+  local file_to_proc=${1}
+  local file_dir=$(dirname $(realpath ${file_to_proc}))
+
+  echo "Fetching external contents for file '${file_to_proc}'"
+
+  while read -r line; do
+    # Check if line is non-empty and ends on .md
+    if [ -n "${line}" ] && [[ "${line}" == *.md ]]; then
+      # If the file exists do nothing, otherwise pull it in from github
+      local file_to_fetch=${file_dir}/${line}
+      if ! ls "${file_to_fetch}" > /dev/null 2>&1; then
+        echo "${line} does not exist. Trying to fetch it from github"
+        local outputdir=$(dirname ${file_to_fetch})
+        mkdir -p ${outputdir}  # make the directory for the output
 
-    # Check again if we hav succesfully fetched the file
-    if ! ls "${line}" > /dev/null 2>&1; then
-      echo "Could not fetch file '${line}' from external sources" 1>&2
-      exit 1
+        # Try a few github organizations
+        for org in key4hep HEP-FCC AIDASoft iLCSoft; do
+          echo "Trying to fetch from github organization: '${org}'"
+          if try_fetch ${org} ${line} ${file_dir}; then
+            echo "Fetched succesfully from organization '${org}'"
+            break
+          fi
+        done
+      fi
+
+      # Check again if we hav succesfully fetched the file
+      if ! ls "${file_to_fetch}" > /dev/null 2>&1; then
+        echo "Could not fetch file '${line}' from external sources" 1>&2
+        exit 1
+      fi
     fi
-  fi
-done < README.md
+  done < ${file_to_proc}
+}
+
+fetch_for_file README.md
+fetch_for_file tutorials/README.md

README.md

@@ -8,11 +8,7 @@
     :caption: Contents:
 
     setup-and-getting-started/README.md
-    k4marlinwrapper/doc/starterkit/k4MarlinWrapperCLIC/Readme.md
-    k4marlinwrapper/doc/starterkit/k4MarlinWrapperCLIC/edmConverters.md
-    k4marlinwrapper/doc/starterkit/k4MarlinWrapperCLIC/howtoMultithread.md
-    k4marlinwrapper/doc/starterkit/k4MarlinWrapperCLIC/CEDViaWrapper.md
-    k4simdelphes/doc/starterkit/k4SimDelphes/Readme.md
+    tutorials/README.md
     developing-key4hep-software/README.md
     spack-build-instructions-for-librarians/README.md
     talks-and-presentations/README.md

tutorials/README.md

@@ -0,0 +1,23 @@
+# Key4hep Tutorials
+
+This page contains several tutorials for working in a Key4hep software stack. We
+try to design and set them up in a way that they can be done at any time but we
+present them at hands-on tutorial sessions as well.
+
+**If you are following these tutorials and run into an issue please let us know
+by [opening an issue](https://github.com/key4hep/key4hep-doc/issues/new/choose)
+on the [`key4hep-doc`](https://github.com/key4hep/key4hep-doc) repository.** If
+you have the feeling that something is missing, we are also very happy to accept
+new tutorial suggestions. If you have a tutorial that you would like to add
+here.
+
+```eval_rst
+.. toctree::
+    :caption: Exercises
+
+    k4marlinwrapper/doc/starterkit/k4MarlinWrapperCLIC/Readme.md
+    k4marlinwrapper/doc/starterkit/k4MarlinWrapperCLIC/edmConverters.md
+    k4marlinwrapper/doc/starterkit/k4MarlinWrapperCLIC/howtoMultithread.md
+    k4marlinwrapper/doc/starterkit/k4MarlinWrapperCLIC/CEDViaWrapper.md
+    k4simdelphes/doc/starterkit/k4SimDelphes/Readme.md
+```

tutorials/example.md

@@ -0,0 +1,3 @@
+# Example
+
+Lorum ipsum and all the rest