Patch up documentation

docs/README.md

@@ -0,0 +1,16 @@
+# Documentation for The Adaptable Input Output System
+
+# Generate User Guide in html with Sphinx
+
+This user guide is hosted in readthedocs: https://adios2.readthedocs.io/en/latest/
+
+To generate the User Guide under docs/user_guide/build/html format from the Sphinx source files:
+
+```bash
+$ cd ADIOS2/docs
+docs$ python3 -m venv .
+docs$ . bin/activate
+docs$ pip3 install -r requirements.txt
+user_guide$ cd user_guide
+user_guide$ make html
+```

docs/requirements.txt

@@ -1,5 +1,31 @@
-sphinx
-blockdiag>=1.5.4
-sphinxcontrib-blockdiag>=1.5.5
-sphinx_rtd_theme>=0.4.1
+alabaster==0.7.12
+Babel==2.8.0
+blockdiag==2.0.1
 breathe==4.18.1
+certifi==2019.11.28
+chardet==3.0.4
+docutils==0.16
+funcparserlib==0.3.6
+idna==2.9
+imagesize==1.2.0
+Jinja2==2.11.1
+MarkupSafe==1.1.1
+packaging==20.1
+Pillow==7.0.0
+Pygments==2.5.2
+pyparsing==2.4.6
+pytz==2019.3
+requests==2.23.0
+six==1.14.0
+snowballstemmer==2.0.0
+Sphinx==3.1.2
+sphinx-rtd-theme==0.4.3
+sphinxcontrib-applehelp==1.0.2
+sphinxcontrib-blockdiag==2.0.0
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==1.0.3
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.4
+urllib3==1.25.8
+webcolors==1.11.1

docs/user_guide/source/api_full/api_full.rst

@@ -4,7 +4,8 @@ Full APIs
 
 .. note::
 
-   Application developers who desire fine-grained control of IO tasks should use the Full APIs. In simple cases (e.g. reading a file for analysis, interactive Python, or saving some data for a small project or tests) please refer to the :ref:High-Level APIs. 
+   Application developers who desire fine-grained control of IO tasks should use the Full APIs.
+   In simple cases (e.g. reading a file for analysis, interactive Python, or saving some data for a small project or tests) please refer to the :ref:`High-Level APIs`.
 
 
 Currently ADIOS2 support bindings for the following languages and their minimum standards:
@@ -27,12 +28,13 @@ Currently ADIOS2 support bindings for the following languages and their minimum
 
 .. tip::
 
-   Prefer the C++11 bindings if your application C++ compiler supports the 2011 (or later) standard. For code using previous C++ standards (98 or 03) use the C bindings for ABI compatibility.   
+   Prefer the C++11 bindings if your application C++ compiler supports the 2011 (or later) standard.
+   For code using previous C++ standards (98 or 03) use the C bindings for ABI compatibility.
 
 
 .. caution::
 
-   Statically linked libraries (``*.a``) might result in conflicting ABIs between an older C++ project, the C bindings, and the adios native C++11 library. Test to make sure it works for your platform. 
+   Statically linked libraries (``*.a``) might result in conflicting ABIs between an older C++ project, the C bindings, and the adios native C++11 library. Test to make sure it works for your platform.
 
 
 The current interaction flow for each language binding API with the ADIOS2 library is specified as follows
@@ -70,4 +72,3 @@ The following sections provide a summary of the API calls on each language and l
 .. include:: fortran.rst
 .. include:: c.rst
 .. include:: python.rst
-

docs/user_guide/source/api_full/cxx11.rst

@@ -88,10 +88,11 @@ The following section provides a summary of the available functionality for each
    :members:
 
 
-Debugging
----------
+**Debugging**
 
-For debugging, ADIOS2 C++11 class instances and enums can be passed directly to ostreams, as well as converted to human-readable strings via the ubiquitous ``ToString(object)`` member variable. You can also directly pass objects to ``ostream``s.
+For debugging, ADIOS2 C++11 class instances and enums can be passed directly to ostreams,
+as well as converted to human-readable strings via the ubiquitous ``ToString(object)`` member variable.
+You can also directly pass objects to an ``ostream``.
 
 Example:
 

docs/user_guide/source/components/adios.rst

@@ -1,42 +1,24 @@
-*****ADIOS *****
+*********
+ADIOS
+*********
 
-         The `adios2::ADIOS` component is the initial contact point between an
-             application and the ADIOS2 library.Applications
-                 can be classified as MPI and non -
-    MPI based.We start by focusing on MPI applications as their non -
-    MPI equivalent just removes the MPI -
-    specific communicator
-        .
+The ``adios2::ADIOS`` component is the initial contact point between an application and the ADIOS2 library.
+Applications can be classified as MPI and non-MPI based.
+We start by focusing on MPI applications as their non-MPI equivalent just removes the MPI communicator.
 
-        ..code -
-    block::c++
+.. code-block:: c++
 
     /** ADIOS class factory of IO class objects */
     adios2::ADIOS adios("config.xml", MPI_COMM_WORLD);
 
 This component is created by passing :
 
-    1. * *Runtime config file **(optional)
-: ADIOS2 xml runtime config file,
-    see : ref :`Runtime Configuration Files` 2. * *MPI communicator *
-    * : which determines the scope of the ADIOS library components in an
-        application.3. *
-    *debug mode flag * * : turns on /
-    off exceptions triggered by user inputs
-        .
-
-        ..note::
-
-            Debug mode is deprecated
-        and will not affect ADIOS2 behavior.Unexpected system failures and
-        runtime errors are always checked by throwing ``std::runtime_error``
-            .Keep in mind that Segmentation Faults are NOT runtime exceptions.We
-        try to keep user interactions as friendly as possible, please report any bugs on GitHub: https://github.com/ornladios/ADIOS2/issues
+    1. **Runtime config file** (optional): ADIOS2 xml runtime config file, see :ref:`Runtime Configuration Files`.
 
+    2. **MPI communicator** : which determines the scope of the ADIOS library components in an application.
 
 ``adios2::ADIOS`` objects can be created in MPI and non-MPI (serial) mode.
 Optionally, a runtime configuration file can be passed to the constructor indicating the full file path, name and extension.
-Thus resulting in:
 
 **Constructors for MPI applications**
 
@@ -45,35 +27,27 @@ Thus resulting in:
     /** Constructors */
 
     // version that accepts an optional runtime adios2 config file
-    adios2::ADIOS (const std::string configFile,
-                   MPI_COMM mpiComm = MPI_COMM_SELF,
-                   const bool debugMode = adios2::DebugON );
+    adios2::ADIOS(const std::string configFile,
+                  MPI_COMM mpiComm = MPI_COMM_SELF);
 
-adios2::ADIOS(MPI_COMM mpiComm = MPI_COMM_SELF,
-              const bool debugMode = adios2::DebugON);
+    adios2::ADIOS(MPI_COMM mpiComm = MPI_COMM_SELF);
 
-/** Examples */
-adios2::ADIOS adios(MPI_COMM_WORLD);
-adios2::ADIOS adios("config.xml", MPI_COMM_WORLD, adios2::DebugOFF);
+    /** Examples */
+    adios2::ADIOS adios(MPI_COMM_WORLD);
+    adios2::ADIOS adios("config.xml", MPI_COMM_WORLD);
 
 **Constructors for non-MPI (serial) applications**
 
 .. code-block:: c++
 
     /** Constructors */
-    adios2::ADIOS (const std::string configFile,
-                   const bool debugMode = adios2::DebugON );
-
-adios2::ADIOS(const bool debugMode = adios2::DebugON);
+    adios2::ADIOS(const std::string configFile);
 
-/** Examples */
-adios2::ADIOS adios("config.xml");
-adios2::ADIOS adios; // Do not use () for empty constructor.
+    adios2::ADIOS();
 
-.. tip::
-
-   ``adios2::DebugON`` and ``adios::DebugOFF`` are aliases to true and false, respectively.
-   Use them for code clarity.
+    /** Examples */
+    adios2::ADIOS adios("config.xml");
+    adios2::ADIOS adios; // Do not use () for empty constructor.
 
 
 **Factory of IO components**: Multiple IO components (IO tasks) can be created from within the scope of an ADIOS object by calling the ``DeclareIO`` function:
@@ -83,35 +57,33 @@ adios2::ADIOS adios; // Do not use () for empty constructor.
     /** Signature */
     adios2::IO ADIOS::DeclareIO(const std::string ioName);
 
-/** Examples */
-adios2::IO bpWriter = adios.DeclareIO("BPWriter");
-adios2::IO bpReader = adios.DeclareIO("BPReader");
+    /** Examples */
+    adios2::IO bpWriter = adios.DeclareIO("BPWriter");
+    adios2::IO bpReader = adios.DeclareIO("BPReader");
 
 This function returns a reference to an existing IO class object that lives inside the ADIOS object that created it.
 The ``ioName`` identifier input must be unique for each IO.
 Trying to declare an IO object with the same name twice will throw an exception.
 IO names are used to identify IO components in the runtime configuration file, :ref:`Runtime Configuration Files`
 
-As shown in the diagram below, each resulting IO object is self-managed and independent, thus providing an adaptable way to perform different kinds of I/O operations. Users must be careful not to create conflicts between system level unique I/O identifiers: file names, IP address and port, MPI Send/Receive message rank and tag, etc.
+As shown in the diagram below, each resulting IO object is self-managed and independent, thus providing an adaptable way to perform different kinds of I/O operations.
+Users must be careful not to create conflicts between system level unique I/O identifiers: file names, IP address and port, MPI Send/Receive message rank and tag, etc.
 
 .. blockdiag::
 
-   diagram
-{
-    default_fontsize = 18;
-    default_shape = roundedbox;
-    default_linecolor = blue;
-    span_width = 150;
-
-    ADIOS->IO_1, B, IO_N[label = "DeclareIO", fontsize = 13];
-    B[shape = "dots"];
-    ADIOS->B[style = "none"];
-}
-
-..tip::
-
-        The ADIOS component is the only one whose memory is owned by the
-            application.Thus applications must decide on its scope.Any
-                other component of the ADIOS2 API refers to a component that
-                    lives inside the ADIOS component(e.g.IO, Operator) or
-    indirectly in the IO component(Variable, Engine)
+    blockdiag {
+        default_fontsize = 18;
+        default_shape = roundedbox;
+        default_linecolor = blue;
+        span_width = 150;
+
+        ADIOS -> IO_1, B, IO_N[label = "DeclareIO", fontsize = 13];
+        B[shape = "dots"];
+        ADIOS -> B[style = "none"];
+    }
+
+.. tip::
+
+    The ADIOS component is the only one whose memory is owned by the application.
+    Thus applications must decide on its scope.
+    Any other component of the ADIOS2 API refers to a component that lives inside the ADIOS component(e.g. IO, Operator) or indirectly in the IO component(Variable, Engine)

docs/user_guide/source/components/overview.rst

@@ -46,7 +46,7 @@ The following section provides a common overview to all languages based on the C
 
 The following figure depicts the components hierarchy from the application's point of view.
 
-.. image:: https://i.imgur.com/y7bkQQt.png : alt: my-picture2
+.. image:: https://i.imgur.com/y7bkQQt.png
 
 * **ADIOS**: the ADIOS component is the starting point between an application and the ADIOS2 library. Applications provide:
     1. the scope of the ADIOS object through the MPI communicator,
@@ -65,4 +65,4 @@ The following figure depicts the components hierarchy from the application's poi
 
 * **Engine**: Engines define the actual system executing the heavy IO tasks at Open, BeginStep, Put, Get, EndStep and Close. Due to polymorphism, new IO system solutions can be developed quickly reusing internal components and reusing the same API. If IO.SetEngine is not called, the default engine is the binary-pack bp file reader and writer: **BPFile**.
 
-* **Operator**: (under development) this component defines possible operations to be applied on adios2 self-describing data. This higher level abstraction is needed to provide support for: Callback functions, Transforms, Analytics functions, Data Models functionality, etc. Any required task will be executed within the Engine. One or many operators can be associated with any of the adios2 objects or a group of them.
+* **Operator**: These define possible operations to be applied on adios2-managed data, for example, compression. This higher level abstraction is needed to provide support for callbacks, transforms, analytics, data models, etc. Any required task will be executed within the Engine. One or many operators can be associated with any of the adios2 objects or a group of them.

docs/user_guide/source/components/variable.rst

@@ -2,15 +2,20 @@
 Variable
 ********
 
-Self-describing Variables are the atomic unit of data representation in the ADIOS2 library when interacting with applications. Thus, the Variable component is the link between a piece of data coming from an application and its self-describing information or metadata. This component handles all application variables classified by data type and shape type.
+Variables are the atomic unit of data representation in the ADIOS2 library when interacting with applications.
+Thus, the Variable component is the link between a piece of data coming from an application and its metadata.
+This component handles all application variables classified by data type and shape type.
 
-Each IO holds its own set of Variables, each Variable is identified with a unique name. They are created using the reference from ``IO::DefineVariable<T>`` or retrieved using the pointer from ``IO::InquireVariable<T>`` functions in :ref:`IO`.
+Each IO holds its own set of Variables, each Variable is identified with a unique name.
+They are created using the reference from ``IO::DefineVariable<T>`` or retrieved using the pointer from ``IO::InquireVariable<T>`` functions in :ref:`IO`.
 
 Variables Data Types
 --------------------
 
 Currently, only primitive types are supported in ADIOS 2. 
-Fixed-width types from `<cinttypes> and <cstdint> <https://en.cppreference.com/w/cpp/types/integer>`_  should be preferred when writing portable code. ADIOS 2 maps primitive "natural" types to its equivalent fixed-width type (e.g. ``int`` -> ``int32_t``). Acceptable values for the type ``T`` in ``Variable<T>`` (this is C++ only, see below for other bindings) along with their preferred fix-width equivalent in 64-bit platforms:
+Fixed-width types from `<cinttypes> and <cstdint> <https://en.cppreference.com/w/cpp/types/integer>`_  should be preferred when writing portable code.
+ADIOS 2 maps primitive "natural" types to its equivalent fixed-width type (e.g. ``int`` -> ``int32_t``).
+Acceptable values for the type ``T`` in ``Variable<T>`` (this is C++ only, see below for other bindings) along with their preferred fix-width equivalent in 64-bit platforms:
 
 .. code-block:: c++
 
@@ -53,10 +58,13 @@ Variables Shape Types
 .. note::
    As of beta release version 2.2.0 local variable reads are not supported, yet. This is work in progress. Please use global arrays and values as a workaround.
 
-ADIOS2 is designed *out-of-the-box* for MPI applications. Thus different application data shape types must be covered depending on their scope within a particular MPI communicator. The shape type is defined at creation from the IO object by providing the dimensions: shape, start, count in the ``IO::DeclareVariable<T>`` template function. The supported Variables by shape types can be classified as:
+ADIOS2 is designed *out-of-the-box* for MPI applications.
+Thus different application data shape types must be covered depending on their scope within a particular MPI communicator.
+The shape type is defined at creation from the IO object by providing the dimensions: shape, start, count in the ``IO::DeclareVariable<T>`` template function.
+The supported Variables by shape types can be classified as:
 
 
-1. **Global Single Value**: only name is required in their definition. This variables are helpful for storing global information, preferably managed by only one MPI process, that may or may not change over steps: *e.g.* total number of particles, collective norm, number of nodes/cells, etc.
+1. **Global Single Value**: only a name is required for their definition. These variables are helpful for storing global information, preferably managed by only one MPI process, that may or may not change over steps: *e.g.* total number of particles, collective norm, number of nodes/cells, etc.
 
    .. code-block:: c++
 
@@ -77,7 +85,7 @@ ADIOS2 is designed *out-of-the-box* for MPI applications. Thus different applica
 
 2. **Global Array**: the most common shape used for storing self-describing data used for analysis that lives in several MPI processes. The image below illustrates the definitions of the dimension components in a global array: shape, start, and count.
 
-   .. image:: https://i.imgur.com/MKwNe5e.png : alt: my-picture2
+   .. image:: https://i.imgur.com/MKwNe5e.png
 
    .. warning::
 
@@ -98,7 +106,7 @@ ADIOS2 is designed *out-of-the-box* for MPI applications. Thus different applica
 
 4. **Local Array**: single array variables that are local to the MPI process. These are more commonly used to write Checkpoint data, that is later read for Restart. Reading, however, needs to be handled differently: each process' array has to be read separately, using SetSelection per rank. The size of each process selection should be discovered by the reading application by inquiring per-block size information of the variable, and allocate memory accordingly.
 
-  .. image:: https://i.imgur.com/XLh2TUG.png : alt: my-picture3
+  .. image:: https://i.imgur.com/XLh2TUG.png
 
 
 5. **Joined Array (NOT YET SUPPORTED)**: in certain circumstances every process has an array that is different only in one dimension. ADIOS2 allows user to present them as a global array by joining the arrays together. For example, if every process has a table with a different number of rows, and one does not want to do a global communication to calculate the offsets in the global table, one can just write the local arrays and let ADIOS2 calculate the offsets at read time (when all sizes are known by any process).

docs/user_guide/source/introduction/nutshell.rst

@@ -32,7 +32,7 @@ The key aspects ADIOS2 are
 
 #. **Commitment:** ADIOS2 is committed to the HPC community, releasing a new version every 6 months.
 
-*ADIOS2 is funded by the Department of Energy as part of the* `Exascale Computing Program <https://www.exascaleproject.org>`_.
+*ADIOS2 is funded by the Department of Energy as part of the* `Exascale Computing Project <https://www.exascaleproject.org>`_.
 
 ************************
 What ADIOS2 is and isn't

docs/user_guide/source/setting_up/linking.rst

@@ -10,7 +10,7 @@ ADIOS exports a CMake package configuration file that allows its targets to be d
 
 .. code-block:: cmake
 
-    cmake_minimum_required(VERSION 3.6)
+    cmake_minimum_required(VERSION 3.12)
     project(MySimulation C CXX)
 
     find_package(MPI REQUIRED)

docs/user_guide/source/setting_up/package.rst

@@ -16,7 +16,7 @@ Currently ADIOS 2 can be obtained from anaconda cloud:
 Spack
 *****
 
-ADIOS 2 is fully supported in the latest Spack `adios2 package <https://spack.readthedocs.io/en/latest/package_list.html#adios2>`_
+ADIOS 2 is packaged in Spack `adios2 package <https://spack.readthedocs.io/en/latest/package_list.html#adios2>`_
 
 
 ******

docs/user_guide/source/setting_up/source.rst

@@ -2,7 +2,7 @@
 Install from Source
 ###################
 
-ADIOS2 uses `CMake <https://cmake.org/>`_ version 3.6 or above, for building,
+ADIOS2 uses `CMake <https://cmake.org/>`_ version 3.12 or above, for building,
 testing and installing the library and utilities.
 
 .. include:: source/cmake.rst

docs/user_guide/source/setting_up/source/cmake.rst

@@ -2,11 +2,6 @@
 Building, Testing, and Installing ADIOS 2
 *****************************************
 
-.. caution::
-
-   Always do a fresh build from scratch if your source is updated with considerable changes *e.g.* `git pull` 
-
-
 To build ADIOS v2.x, clone the repository and invoke the canonical CMake build sequence:
 
 .. code-block:: bash