From 1a3d71199114a5ff40fc03e43d864d387da68c6e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Franz=20P=C3=B6schel?= <franz.poeschel@gmail.com>
Date: Wed, 31 Jul 2024 16:41:31 +0200
Subject: [PATCH] Documentation

---
 docs/source/backends/hdf5.rst         | 6 +++++-
 docs/source/details/backendconfig.rst | 7 +++++++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/docs/source/backends/hdf5.rst b/docs/source/backends/hdf5.rst
index 0f839648c8..1d1866d874 100644
--- a/docs/source/backends/hdf5.rst
+++ b/docs/source/backends/hdf5.rst
@@ -22,7 +22,7 @@ Rudimentary support for HDF5 VFDs (`virtual file driver <https://www.hdfgroup.or
 Note that the subfiling VFD needs to be enabled explicitly when configuring HDF5 and threaded MPI must be used.
 
 Virtual file drivers are configured via JSON/TOML.
-Refer to the page on `JSON/TOML configuration <backendconfig-hdf5>`_ for further details.
+Refer to the page on :ref:`JSON/TOML configuration <backendconfig-hdf5>` for further details.
 
 
 Backend-Specific Controls
@@ -54,6 +54,10 @@ Although we choose the default to be non-collective (independent) for ease of us
 For independent parallel I/O, potentially prefer using a modern version of the MPICH implementation (especially, use ROMIO instead of OpenMPI's ompio implementation).
 Please refer to the `HDF5 manual, function H5Pset_dxpl_mpio <https://support.hdfgroup.org/HDF5/doc/RM/H5P/H5Pset_dxpl_mpio.htm>`_ for more details.
 
+.. tip::
+
+  Instead of using an environment variable, independent/collective data transfer can also be configured at the API level via :ref:`JSON/TOML <backendconfig-hdf5>`.
+
 ``OPENPMD_HDF5_ALIGNMENT``: this sets the alignment in Bytes for writes via the ``H5Pset_alignment`` function.
 According to the `HDF5 documentation <https://support.hdfgroup.org/HDF5/doc/RM/H5P/H5Pset_alignment.htm>`_:
 *For MPI IO and other parallel systems, choose an alignment which is a multiple of the disk block size.*
diff --git a/docs/source/details/backendconfig.rst b/docs/source/details/backendconfig.rst
index fae114a01c..dca9b046e3 100644
--- a/docs/source/details/backendconfig.rst
+++ b/docs/source/details/backendconfig.rst
@@ -211,6 +211,13 @@ Explanation of the single keys:
     * ``hdf5.vfd.stripe_size``: Must be an integer
     * ``hdf5.vfd.stripe_count``: Must be an integer
 
+Flush calls, e.g. ``Series::flush()`` can be configured via JSON/TOML as well.
+The parameters eligible for being passed to flush calls may be configured globally as well, i.e. in the constructor of ``Series``, to provide default settings used for the entire Series.
+
+* ``hdf5.independent_stores``: A boolean that sets the ``H5FD_MPIO_INDEPENDENT`` dataset transfer property if true, otherwise ``H5FD_MPIO_COLLECTIVE``.
+  Only available when using HDF5 in combination with MPI.
+  See the `HDF5 subpage <backends-hdf5>`_ for further information on independent vs. collective flushing.
+
 .. _backendconfig-other:
 
 Other backends