Merge pull request #945 from williamfgc/docs

Unified rtd ADIOS2 project and links

ReadMe.md

@@ -19,11 +19,7 @@ ADIOS >= 2.0 is licensed under the Apache License v2.0.  See the accompanying
 Copyright.txt for more details.
 
 ## Documentation
-Please find ADIOS2 software documentation for:
-
-1. [ADIOS2 User Guide at readthedocs](https://adios2-adaptable-io-system-version-2.readthedocs.io)
-
-2. Local user guide documentation generation [docs/ReadMe.md](docs/ReadMe.md)
+Please find [ADIOS2 User Guide at readthedocs](https://adios2.readthedocs.io)
 
 ## Directory layout
 * cmake - Project specific CMake modules
@@ -32,8 +28,8 @@ Please find ADIOS2 software documentation for:
 * source - ADIOS2 source  
     * adios2 - source directory for the ADIOS2 library to be installed under install-dir/lib/libadios2.  
     * utils  - source directory for the binary utilities, to be installed under install-dir/bin  
-* bindings - public interface language bindings (C++11, C++98, C, Fortran and Python)
-* testing - Tests using gtest
+* bindings - public interface language bindings (C++11, C++98, C, Fortran, Python and Matlab)
+* testing - Tests using [gtest](https://github.com/google/googletest)
 
 
 ## Getting Started
@@ -42,7 +38,7 @@ ADIOS2 uses CMake for its build environment.  CMake expects projects
 to use "out-of-source" builds, which means keeping a separate build and source
 directory (different from autotools, which usually uses an in-source build).
 
-The following is a quick step-by-step build guide, find the full CMake-based install documentation [here](http://adios2-adaptable-io-system-version-2.readthedocs.io/en/latest/installation/installation.html)
+The following is a quick step-by-step build guide, find the full CMake-based install documentation [here](http://adios2.readthedocs.io/en/latest/installation/installation.html)
 
 Step-by-step build guide:
 

docs/user_guide/source/api_simple/api_simple.rst

@@ -2,16 +2,16 @@
 Simple Language Bindings APIs
 #############################
 
-The current simple APIs are designed for simple and direct tasks in which performance is not a critical aspect. Unlike the :ref:`Full Language Bindings APIs` the simple APIs only require a single object/handler. Thus offering a nearly-flat learning curve.
+The current simple APIs are designed for simple and direct tasks in which performance is not a critical aspect. Unlike the :ref:`Full Language Bindings APIs` the simple APIs only require a single object/handler. Thus offering a nearly-flat learning curve for first-time users.
 
 Typical scenarios for using the simple APIs are:
 
 * Reading a file to perform data analysis with libraries (matplotlib, scipy, etc.)
 * Interactive: few calls make interactive usage easier. 
 * Saving data to files is small or personal projects
-* Notebooks: **e.g.** Jupyter 
+* Online frameworks: **e.g.** Jupyter notebooks
 
-The designed functionality syntax is closely related to the native language IO bindings for formatted text IO **e.g.** C++ fstream, C FILE*, Fortran and Python file IO. The main function calls are: ``open`` (or constructor in C++), ``write``, ``read`` and ``close`` (or destructor in C++), with the corresponding language native syntax for advancing the step in write mode, and for a "step-by-step" streaming basis in read mode. See each language section for an example.
+The designed functionality syntax is closely related to the native language IO bindings for formatted text IO **e.g.** C++ fstream, C FILE*, Fortran and Python file IO. The main function calls are: ``open`` (or constructor in C++), ``write``, ``read`` and ``close`` (or destructor in C++). In addition, ADIOS2 borrows the corresponding language native syntax for advancing lines to advance the step in write mode, and for a "step-by-step" streaming basis in read mode. See each language section in this chapter for a write/read example.
 
 .. warning::
 

docs/user_guide/source/components/engine.rst

@@ -102,7 +102,7 @@ The following example illustrates the basic API usage in write mode for data gen
 .. danger::
    The default behavior of adios2 Put and Get calls IS NOT synchronized, but rather deferred. It's actually the opposite of MPI_Put and more like MPI_rPut.
    Do not assume the data pointer is usable after a Put and Get, before EndStep, Close or the corresponding PerformPuts/PerformGets. 
-   Be SAFE and use the adios2::Mode::Sync in the 3rd argument. 
+   Be SAFE and consider using the adios2::Mode::Sync in the 3rd argument. Avoid using TEMPORARIES, r-values, and out-of-scope variables in Deferred mode.
 
 
 Available Engines

docs/user_guide/source/components/overview.rst

@@ -2,13 +2,32 @@
 Components Overview
 *******************
 
-The simple way to understand the big picture for the ADIOS2 core components is to map each class to the actual definition of the ADIOS acronym.
+.. note::
 
-============== =========== ============== ============
- Acronym Word   ADaptable   Input/Output     System   
-============== =========== ============== ============
- Component      **ADIOS**      **IO**      **Engine** 
-============== =========== ============== ============
+   If you are doing simple tasks where performance is a non-critical aspect please go to the :ref:`Simple Language Bindings APIs` section for a quick start. If you are an HPC application developer or you want to use ADIOS2 functionality in full please read this chapter.
+
+
+The simple way to understand the big picture for the ADIOS2 unified user interface components is to map each class to the actual definition of the ADIOS acronym.
+
++------------+-----------+---------------------------+
+| Component  | Acronym   | Function                  |
++------------+-----------+---------------------------+
+|            |           | Set MPI comm domain       |
+|            |           |                           |
+| **ADIOS**  | ADaptable | Set runtime settings      |
+|            |           |                           |
+|            |           | Own other components      |
++------------+-----------+---------------------------+
+|            |           | Set engine                |
+|            |           |                           |
+| **IO**     | I/O       | Set variables/attributes  |
+|            |           |                           |
+|            |           | Set compile-time settings |
++------------+-----------+---------------------------+
+|            |           | Execute heavy IO tasks    |
+| **Engine** | System    |                           |
+|            |           | Manage system resources   |
++------------+-----------+---------------------------+
 
 
 ADIOS2's public APIs are based on the natural choice for each supported language to represent each ADIOS2 components and its interaction with application datatypes. Thus, 

docs/user_guide/source/faq/faq.rst

@@ -20,7 +20,7 @@ APIs
 Building on Titan
 *****************
 
-#. :ref:`My application uses PGI on Titan, can I link ADIOS 2?`
+#. :ref:`My application uses PGI compilers on Titan, can I link ADIOS 2?`
 #. :ref:`How do I enable the Python bindings on Titan?`
 
 
@@ -67,8 +67,8 @@ you must use sync mode with adios2_put. Deferred mode will save garbage data sin
 
 
 
-My application uses PGI on Titan, can I link ADIOS 2?
------------------------------------------------------
+My application uses PGI compilers on Titan, can I link ADIOS 2?
+---------------------------------------------------------------
 
 Follow directions at :ref:`Building on High Performance Computing, HPC, Systems` to setup support for PGI on Titan. PGI compilers depend on GNU headers, but they must point to a version greater than gcc 4.8.1 to support C++11 features. The gcc module doesn't need to be loaded, though. Example: