Version 1.0.0 (#104)

* doc tweaks [skip ci]

* much happier with docs [skip ci]

* updates from Huub

docs/README.md

@@ -23,30 +23,55 @@ ParallelZone's documentation has two parts:
 - The Doxygen-generated C++ API documentation
 
 The C++ API documentation is built as part of the build process and then moved
-to `docs/source/parallelzone_cxx_api`. When the Sphinx front-end documentation is built 
-it will link to the C++ documentation. If the C++ documentation does not exist,
-building the Sphinx front-end will still work, but the link to the C++ API won't
-work.
+to `docs/source/parallelzone_cxx_api`. When the Sphinx front-end documentation
+is built it will link to the C++ documentation. If the C++ documentation does
+not exist, building the Sphinx front-end will still work, but the link to the
+C++ API won't work.
 
-Building the Sphinx Front-End
------------------------------
+Building the C++ Documentation
+------------------------------
 
-The Sphinx front-end of the documentation requires the following Python packages
-(all can be installed with pip):
+The C++ documentation is built by Doxygen. You will need to have Doxygen
+installed on your system (it is likely available in your operating system's
+package manager, *e.g.*, try `apt-get install doxygen`). By default, when you
+run CMake on ParallelZone, building documentation is disabled. To enable it,
+either pass `BUILD_DOCS=TRUE` to the CMake command, or (preferred) set
+`BUILD_DOCS` to true in your toolchain file. Optionally, you may set
+`ONLY_BUILD_DOCS` to `TRUE` if you would like to skip building ParallelZone
+(useful, for example, if you are iterating on the documentation locally). As
+an example:
+
+```.sh
+# In the ParallelZone repository's root
+cmake -H. -Bbuild -DBUILD_DOCS=TRUE -DONLY_BUILD_DOCS=TRUE
+cmake --build build --target parallelzone_cxx_api
+```
 
-- sphinx_rtd_theme (The Read-The-Docs theme for sphinx)
-- sphinx (The thing that makes the documenation)
+When you are done building there should be a file `build/html/index.html`, this
+is the entry point into the C++ API docs. Unfortunately, Sphinx does not allow
+you to link to files which reside in parent directories of the `conf.py` file,
+hence the link to the C++ API in the Sphinx documentation can not be made to
+point to `build/html/index.html`. It is thus easier to view the C++ API
+documentation separately by directing your web browser directly at
+`build/html/index.html`.
+
+Building the Sphinx Front-End
+-----------------------------
 
-To build the Sphinx front-end of the documentation it is recommended that you
-use Python's virtual environments. Assuming you want to call your virtual
-environment `parallelzone_venv` the steps are (run from this directory):
+The Sphinx front-end of the documentation requires several Python packages to
+be installed (see the `requirements.txt` file). These packages are all available
+from PIP. The workflow below shows how to setup a Python virtual environment,
+download the dependencies, and build the Sphinx documentation. For the sake
+of this tutorial we assume you want to call your virtual
+environment `parallelzone_venv`:
 
 ```.bash
+# In the docs/ directory
 python3 -m venv parallelzone_venv
 source parallelzone_venv/bin/activate
 pip install -r requirements.txt
 make html
 ```
 
-You can then point your webbrowser at `build/html/index.html` to view the 
+You can then point your webbrowser at `docs/build/html/index.html` to view the
 documentation.

docs/source/abbreviations.rst → docs/source/background/abbreviations.rst

@@ -19,9 +19,10 @@
 Abbreviations Used Throughout ParallelZone
 ##########################################
 
-The following subsections list (in alphabetical order) abbreviations encountered
-throughout ParallelZone. Pages are encouraged to link to each abbreviation on
-its first use.
+The following is a list (in alphabetical order) of abbreviations encountered
+throughout ParallelZone. Pages are encouraged to use these abbreviations and
+to link to the abbreviation on its first use (instead of defining the
+abbreviation).
 
 .. _api:
 

docs/source/about.rst → docs/source/background/about.rst

@@ -24,53 +24,7 @@ The ParallelZone Worldview
    GPUs, *etc.*) that processes have direct/local access to.
 
 To use ParallelZone it is helpful to understand the abstraction model at a high
-level. ParallelZone expands on the :ref:`MPI` model. So we start with a brief
-review of MPI.
-
-**********
-MPI Primer
-**********
-
-:numref:`fig_mpi_runtime` illustrates a simplified version of how MPI sees a
-program. The view is process-centric. When the program starts, MPI defines a
-set ``MPI_COMM_WORLD`` which includes all of program's processes. Within our
-example ``MPI_COMM_WORLD`` has three processes. MPI assigns these processes an
-integer value (ranging from 0 to "the number of processes minus 1") called the
-process's rank. More complicated MPI setups can have further partition
-``MPI_COMM_WORLD`` into subsets, but the overall point remains: MPI's view of
-a program is a series of processes somehow grouped together.
-
-.. _fig_mpi_runtime:
-
-.. figure:: assets/mpi.png
-   :align: center
-
-   Illustration of MPI's runtime abstraction model.
-
-In a typical MPI-based program parallelism is expressed by somehow mapping tasks
-and data to ranks. For example say we have three arbitrary functions ``foo``,
-``bar``, and ``baz` and a chunk of data we want to run ``foo``, ``bar``, and
-``baz`` on. :numref:`fig_mpi_mappings` shows the three ways we can do this in
-parallel.
-
-.. _fig_mpi_mappings:
-
-.. figure:: assets/mpi_mappings.png
-   :align: center
-
-   Possible ways of mapping data and tasks to MPI ranks.
-
-In the :ref:`simd` approach depicted at the top of :numref:`fig_mpi_mappings` we
-distribute the data over the MPI ranks and have each rank pass its local chunk
-of data to the three functions. In :ref:`misd`, which is shown in the middle of
-:numref:`fig_mpi_mappings` we instead distribute the functions over the ranks.
-Finally, in the :ref:`mimd` model shown at the bottom of
-:numref:`fig_mpi_mappings` we distribute both the data and the functions.
-
-Unfortunately on today's machines it takes more than distributing tasks and/or
-data to otherwise opaque ranks to achieve high-performance. This is because
-the performance also depends on the hardware available to each rank and how
-well utilized that hardware is.
+level.
 
 *********************
 Focusing on Resources

docs/source/background/index.rst

@@ -0,0 +1,29 @@
+.. Copyright 2023 NWChemEx-Project
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+#######################
+ParallelZone Background
+#######################
+
+The topics in this section are intended to provide the interested reader with an
+overview of the concepts underlying ParallelZone and the history leading up to
+the development of ParallelZone. Readers wanting to know how to use ParalellZone
+should skip ahead to :ref:`installing_parallelzone`.
+
+.. toctree::
+   :maxdepth: 1
+
+   abbreviations
+   mpi_primer
+   about

docs/source/background/mpi_primer.rst

@@ -0,0 +1,59 @@
+.. Copyright 2023 NWChemEx-Project
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+##########
+MPI Primer
+##########
+
+:numref:`fig_mpi_runtime` illustrates a simplified version of how :ref:`mpi`
+sees a program. The view is process-centric. When the program starts, MPI
+defines a
+set ``MPI_COMM_WORLD`` which includes all of program's processes. Within our
+example ``MPI_COMM_WORLD`` has three processes. MPI assigns these processes an
+integer value (ranging from 0 to "the number of processes minus 1") called the
+process's rank. More complicated MPI setups can have further partition
+``MPI_COMM_WORLD`` into subsets, but the overall point remains: MPI's view of
+a program is a series of processes somehow grouped together.
+
+.. _fig_mpi_runtime:
+
+.. figure:: assets/mpi.png
+   :align: center
+
+   Illustration of MPI's runtime abstraction model.
+
+In a typical MPI-based program parallelism is expressed by somehow mapping tasks
+and data to ranks. For example say we have three arbitrary functions ``foo``,
+``bar``, and ``baz` and a chunk of data we want to run ``foo``, ``bar``, and
+``baz`` on. :numref:`fig_mpi_mappings` shows the three ways we can do this in
+parallel.
+
+.. _fig_mpi_mappings:
+
+.. figure:: assets/mpi_mappings.png
+   :align: center
+
+   Possible ways of mapping data and tasks to MPI ranks.
+
+In the :ref:`simd` approach depicted at the top of :numref:`fig_mpi_mappings` we
+distribute the data over the MPI ranks and have each rank pass its local chunk
+of data to the three functions. In :ref:`misd`, which is shown in the middle of
+:numref:`fig_mpi_mappings` we instead distribute the functions over the ranks.
+Finally, in the :ref:`mimd` model shown at the bottom of
+:numref:`fig_mpi_mappings` we distribute both the data and the functions.
+
+Unfortunately on today's machines it takes more than distributing tasks and/or
+data to otherwise opaque ranks to achieve high-performance. This is because
+the performance also depends on the hardware available to each rank and how
+well utilized that hardware is.

docs/source/developer/design/ram.rst

@@ -132,7 +132,7 @@ Examples of one-to-one communications
    }
 
    // Sends the data to rank 1, type U determined by template meta-programming
-   std::optional<U> output = rt.at(1).ram().send(data);
+   std::optional<U> output = rt.at(1).ram().send(data, "some tag");
 
    if(output.has_value()){
        // This part is only run by rank 1

docs/source/developer/design/runtime_view.rst

@@ -101,7 +101,20 @@ Examples of all-to-all communications
    auto data = generate_data();
 
    // This is an all gather
-   auto output = rt.gather<RAM>(data);
+   auto output = rt.gather(data);
 
    // This is an all reduce
-   auto output2 = rt.reduce<RAM>(data, op);
+   auto output2 = rt.reduce(data, op);
+
+.. note::
+
+   As written the APIs assume the data is going to/from RAM. If we eventually
+   want to support other memory spaces we could create overloads which take the
+   target space. In particular we note that we can NOT do things like:
+
+   .. code-block:: c++
+
+      auto output = rt.my_resource_set().ram().gather(data);
+
+   because that would result in deadlock (it calls a series of all-to-one calls
+   where each rank thinks it's the root).

docs/source/developer/index.rst

@@ -18,13 +18,13 @@ Developer Documentation
 
 The documentation in this section is intended primarily for people who are
 interested in developing for, or understanding the internals of ParallelZone.
-As part of the NWChemEx organization, developers may also find the
-`NWChemEx Developer Documentation
-<https://nwchemex-project.github.io/.github/>`__` to be useful.
+The documentation in this section is specific to the design and development of
+ParallelZone. Since ParallelZone is developed by the NWChemEx organization,
+developers may also find the more general `NWChemEx Developer Documentation
+<https://nwchemex-project.github.io/.github/>`__ to be useful.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-   repo_layout
    design/index

docs/source/index.rst

@@ -44,10 +44,9 @@ Planned features:
    :maxdepth: 1
    :caption: Contents:
 
+   background/index
    install
-   abbreviations
    quickstart
-   about
    user/index
    developer/index