Improve doc with an example to list available IDSs

docs/source/courses/basic/analyze.rst

@@ -246,3 +246,20 @@ Exercise 5
             A plot of :math:`T_e` vs :math:`t`.
 
 .. seealso:: :ref:`Lazy loading`
+
+
+Explore the DBEntry and occurrences
+'''''''''''''''''''''''''''''''''''
+
+You may not know a priori which types of IDSs are available within an IMAS database entry.
+It can also happen that several IDSs objects of the same type are stored within
+this entry, in that case each IDS is stored as a separate `occurrence`
+(occurrences are identified with an integer value, 0 being the default).
+
+In IMAS-Python, the function :meth:`~imas.db_entry.DBEntry.list_all_occurrences()` will
+help you finding which occurrences are available in a given database entry and for a given
+IDS type.
+
+The following snippet shows how to list the available IDSs in a given database entry:
+
+.. literalinclude:: imas_snippets/explore_data_entry.py

docs/source/courses/basic/explore.rst

@@ -7,8 +7,8 @@ In this part of the training, we will learn how to use Python to explore data
 saved in IDSs.
 
 
-Explore which IDSs are available
---------------------------------
+Explore which IDS structures are available
+------------------------------------------
 
 Most codes will touch multiple IDSs inside a single IMAS data entry. For example
 a heating code using a magnetic equilibrium from the ``equilibrium`` IDS with a

docs/source/courses/basic/imas_snippets/explore_data_entry.py

@@ -0,0 +1,11 @@
+import imas
+
+# Open input data entry 
+entry = imas.DBEntry("imas:hdf5?path=<...>", "r")
+
+# Print the list of available IDSs with their occurrence
+for idsname in imas.IDSFactory().ids_names():
+    for occ in entry.list_all_occurrences(idsname):
+        print(idsname, occ)
+
+entry.close()