doc: rewording

Author: wkliao

docs/source/api/attribute_api.rst

@@ -1,8 +1,11 @@
 ===========
-Attribute
+Attributes
 ===========
 
-In the library, netCDF attributes can be created, accessed, and manipulated
-using python dictionary-like syntax. A Pythonic interface for metadata operations
-is provided both in the ``File`` class (for global attributes) and the 
-``Variable`` class (for variable attributes).
+NetCDF attributes can be created, accessed, and manipulated using python
+dictionary-like syntax. An attribute can be associated to the file, referred to
+as ``golbal attribute``, as well as to individual variable, referred to as
+``variable's attribute``. Pythonic interfaces for accessing attributes are is
+provided both in :class:`pnetcdf.File` (for global attributes) and the
+:class:`pnetcdf.Variable` (for variable attributes).
+

docs/source/api/dimension_api.rst

@@ -1,10 +1,11 @@
 ==============
-Dimension
+Dimensions
 ==============
 
-Dimension defines the shape and structure of variables and stores coordinate
-data for multidimensional arrays. The ``Dimension`` object, which is also a key
-component of ``File`` class, provides an interface to access dimensions.
+Class ``Dimension`` is used to define the shape of NetCDF variables. In NetCDF,
+a variable, an instance of :class:`pnetcdf.Variable`, is a multi-dimensional
+array. Methods in :class:`pnetcdf.Dimension` provide an interface to access
+dimensions objects stored in the file.
 
 .. autoclass:: pnetcdf::Dimension
    :members: getfile, isunlimited
@@ -24,7 +25,8 @@ Read-only Python Attributes of Dimension Class
 
  .. attribute:: size
 
-    The current size of Dimension (calls ``len`` on Dimension instance).
+    The current size of Dimension (its value can be obtained by calling
+    python function ``len()`` on the Dimension instance).
 
     **Type:** `int`
 

docs/source/api/file_api.rst

@@ -1,12 +1,12 @@
 ================
-File
+Files
 ================
 
-``pnetcdf.File`` is a high-level object representing an netCDF file,
-which provides a Pythonic interface to create, read and write within
-an netCDF file. A File object serves as the root container for dimensions,
-variables, and attributes. Together they describe the meaning of data and
-relations among data fields stored in a netCDF file.
+An instance of class ``pnetcdf.File`` is a high-level object representing a
+netCDF file. The class methods provide a set of Pythonic interfaces to create,
+read and write a netCDF file. A ``File`` instance serves as the root container
+for dimensions, variables, and attributes.  Together they describe the meaning
+of data and relations among data objects stored in a netCDF file.
 
 .. autoclass:: pnetcdf::File
    :members: __init__, close, filepath, redef, enddef, begin_indep, end_indep,
@@ -24,14 +24,14 @@ Read-only Python Attributes of File Class
    .. attribute:: dimensions
 
       The dimensions dictionary maps the names of dimensions defined in this
-      file as an instance of the ``pnetcdf.Dimension`` class.
+      file as an instance of the :class:`pnetcdf.Dimension`.
 
       **Type:** `dict`
 
    .. attribute:: variables
 
       The variables dictionary maps the names of variables defined in this file
-      as an instance of the ``pnetcdf.Variable`` class.
+      as an instance of the :class:`pnetcdf.Variable`.
 
       **Type:** `dict`
 

docs/source/api/function_api.rst

@@ -1,5 +1,5 @@
 ================
-Utility Functions
+Other PnetCDF Utility Functions
 ================
 
 .. autofunction:: pnetcdf::libver

docs/source/api/variable_api.rst

@@ -1,14 +1,16 @@
 =========
-Variable
+Variables
 =========
 
-Variable is a core component of a netCDF file representing an array of data
+``Variable`` is a core component of a netCDF file representing an array of data
 values organized along one or more dimensions, with associated metadata in the
-form of attributes. The ``Variable`` object in the library provides operations
-to read and write the data and metadata of a variable within a netCDF file.
-Particularly, data mode operations have a flexible interface, where reads and
-writes can be done through either explicit function-call style methods or
-indexer-style (numpy-like) syntax.
+form of attributes. An instance of class :class:`pnetcdf.Variable` represents a
+NetCDF variable stored in the file. The class methods provide I/O operations to
+read and write the data and metadata of a NetCDF variable.
+
+Reading and writing a subarray of a variable can be done through either
+explicit function-call style methods or Python indexer-style (numpy-like)
+syntax.
 
 .. autoclass:: pnetcdf::Variable
    :members: ncattrs, put_att, get_att, del_att, rename_att, get_dims,

docs/source/copyright.rst

@@ -2,10 +2,8 @@
 Copyright Statement
 ================
 
-::
-
-    Copyright (c) 2024 Northwestern University and Argonne National
-    Laboratory All rights reserved.
+    Copyright (c) 2024 Northwestern University and Argonne National Laboratory
+    All rights reserved.
 
     Portions of this software were developed by the Unidata Program at the
     University Corporation for Atmospheric Research.

docs/source/index.rst

@@ -3,16 +3,17 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-PnetCDF-Python Documentation
+PnetCDF-Python User Guide
 ============================
 
 **Release:** |release|
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Introduction
-
-   introduction/overview
+PnetCDF-python is a Python interface to PnetCDF, a high-performance parallel
+I/O library for accessing netCDF files.  This integration with Python allows
+for easy manipulation, analysis, and visualization of netCDF data using the
+rich ecosystem of Python's scientific computing libraries, making it a valuable
+tool for python-based applications that require high-performance access to
+netCDF files.
 
 .. toctree::
    :maxdepth: 2
@@ -32,15 +33,16 @@ PnetCDF-Python Documentation
 
 .. toctree::
    :maxdepth: 3
-   :caption: API Documentation
+   :caption: API Reference
 
    api/file_api
    api/dimension_api
    api/variable_api
+   api/attribute_api
    api/function_api
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Copyright Statement
 
    copyright

docs/source/tutorial/basic.rst

@@ -6,12 +6,12 @@ Basics
 Running Python scripts with MPI
 -------------------------------
 
- Python programs with PnetCDF-Python can be run with the command
- :program:`mpiexec`. In practice, running Python programs looks like:
+ Python programs using PnetCDF-Python can be run with the command
+ :program:`mpiexec`. In practice, running a Python program looks like:
 
-  $ mpiexec -n 4 Python script.py
+  $ mpiexec -n 4 python script.py
 
- to run the program with 4 processors.
+ to run the program with 4 MPI processes.
 
 Creating/Opening/Closing a netCDF file
 --------------------------------------
@@ -27,24 +27,24 @@ Creating/Opening/Closing a netCDF file
  Closing the netCDF file is accomplished via the :meth:`File.close` method of
  the ``File`` instance.
 
- Here's an example:
+ Here is an example of creating a new file:
 
  .. code-block:: Python
 
-    from pnetcdf import File
     from mpi4py import MPI
-    comm = MPI.COMM_WORLD
-    f = File(filename="testfile.nc", mode='w', comm=comm, info=None)
+    import pnetcdf
+
+    f = pnetcdf.File(filename="testfile.nc", mode='w', comm=MPI.COMM_WORLD, info=None)
     f.close()
 
- Equivalent example codes in ``netCDF4-python``:
+ Equivalent example codes when using ``netCDF4-python``:
 
  .. code-block:: Python
 
     from mpi4py import MPI
-    from netCDF4 import Dataset
-    comm = MPI.COMM_WORLD
-    f = Dataset(filename="testfile.nc", mode="w", comm=comm, parallel=True)
+    import netCDF4
+
+    f = netCDF4.Dataset(filename="testfile.nc", mode="w", comm=MPI.COMM_WORLD, parallel=True)
     f.close()
 
  For the full example program, see ``examples/craete_open.py``.
@@ -54,11 +54,11 @@ Dimensions
 
  NetCDF variables are multi-dimensional arrays. Before creating any variables,
  the dimensions they depend on must be established. To create a dimension, the
- :meth:`File.def_dim` method is called on a File instance under define mode.
+ :meth:`File.def_dim` method is called on a ``File`` instance under define mode.
  The dimension's name is set using a Python string, while the size is defined
  using an integer value. To create an unlimited dimension (a dimension that can
- be expanded), the size can be omitted or assigned as -1. A "Dimension" object
- will be returned as a handler for this dimension.
+ be expanded), the parameter size can be omitted or assigned as -1. A
+ ``Dimension`` instance will be returned as a handler for this dimension.
 
  Here's an example (same if using netcdf4-python):
 
@@ -70,8 +70,8 @@ Dimensions
     lat_dim = f.def_dim(LAT_NAME, LAT_LEN)
     time_dim = f.def_dim(TIME_NAME, -1)
 
- All of the Dimension instances are stored in a dictionary as an Python
- attribute of File.
+ All of the ``Dimension`` instances are stored in a Python dictionary as an
+ attribute of ``File``.
 
  .. code-block:: Python
 
@@ -94,13 +94,13 @@ Variables
 ------------
 
  NetCDF variables are similar to multidimensional array objects in Python
- provided by the numpy module. To define a netCDF variable, you can utilize the
- :meth:`File.def_var` method within a File instance under define mode. The
- mandatory arguments for this methods include the variable name (a string in
- Python) and dimensions (either a tuple of dimension names or dimension
+ provided by the ``numpy`` module. To define a netCDF variable, you can utilize
+ the :meth:`File.def_var` method within a ``File`` instance under define mode.
+ The mandatory arguments for this methods include the variable name (a string
+ in Python) and dimensions (either a tuple of dimension names or dimension
  instances). In addition, the user need to specify the datatype of the variable
- using module-level NC constants (e.g. pnetcdf.NC_INT).  The supported
- data types given each file format can be found :ref:`here<Datatype>`.
+ using module-level constants (e.g. ``pnetcdf.NC_INT``).  The supported data
+ types given each file format can be found :ref:`here<Datatype>`.
 
  Here's an example (same if using netcdf4-python):
 
@@ -132,7 +132,7 @@ Attributes
  In a netCDF file, there are two types of attributes: global attributes and
  variable attributes.  Global attributes are usually related to the netCDF file
  as a whole and may be used for purposes such as providing a title or
- processing history for a netCDF file. Variable's attributes are used to
+ processing history for a netCDF file. ``Variable``'s attributes are used to
  specify properties related to the variable, such as units, special values,
  maximum and minimum valid values, and annotation.
 
@@ -144,11 +144,11 @@ Attributes
  .. code-block:: Python
 
     # set global attributes
-    f.floatatt = math.pi # Option1: Python attribute assignment
-    f.put_att("intatt", np.int32(1)) # Option2: method put_att()
+    f.floatatt = math.pi # Option 1: Python attribute assignment
+    f.put_att("intatt", np.int32(1)) # Option 2: method put_att()
     f.seqatt = np.int32(np.arange(10))
 
-    # set variable attributes
+    # write variable attributes
     var = f.variables['var']
     var.floatatt = math.pi
     var.put_att("int_att", np.int32(1))
@@ -159,8 +159,8 @@ Attributes
  .. code-block:: Python
 
     # set root group attributes
-    f.floatatt = math.pi # Option1: Python attribute assignment
-    f.setncattr("intatt", np.int32(1)) # Option2: method setncattr()
+    f.floatatt = math.pi # Option 1: Python attribute assignment
+    f.setncattr("intatt", np.int32(1)) # Option 2: method setncattr()
     f.seqatt = np.int32(np.arange(10))
 
     # set variable attributes
@@ -169,10 +169,10 @@ Attributes
     var.setncattr("int_att", np.int32(1))
     var.seqatt = np.int32(np.arange(10))
 
- The :meth:`File.ncattrs` method of a File or Variable instance can be used to
- retrieve the names of all the netCDF attributes. And the __dict__ attribute of
- a File or Variable instance provides all the netCDF attribute name/value pairs
- in a python dictionary:
+ The :meth:`File.ncattrs` method of a ``File`` or ``Variable`` instance can be
+ used to retrieve the names of all the netCDF attributes. And the __dict__
+ attribute of a ``File`` or ``Variable`` instance provides all the netCDF
+ attribute name/value pairs in a python dictionary:
 
  .. code-block:: Python
 
@@ -184,14 +184,14 @@ Attributes
 
  For the full example program, see ``examples/global_attributes.py``.
 
-Writing to variable
+Writing to a variable
 --------------------
 
  Once a netCDF variable instance is created, writing the variable must be done
  while the file is in data mode.  Then for writing, there are two options:
 
-Option1 Indexer (or slicing) syntax
- You can just treat the variable like an numpy array and assign data
+Option 1 Indexer (or slicing) syntax
+ You can just treat the variable like an ``numpy`` array and assign data
  to a slice. Slices are specified as a `start:stop:step` triplet.
 
  .. code-block:: Python
@@ -202,9 +202,9 @@ Option1 Indexer (or slicing) syntax
  The indexer syntax is the same as in ``netcdf4-python`` library for writing to
  netCDF variable.
 
-Option2 Method calls of put_var()/get_var()
- Alternatively you can also leverage Variable.put/get_var() method of a
- Variable instance to perform I/O according to specific access pattern needs.
+Option 2 Method calls of put_var()/get_var()
+ Alternatively you can also leverage ``Variable.put/get_var()`` method of a
+ ``Variable`` instance to perform I/O according to specific access pattern needs.
 
  Here is the example below to write an array to the netCDF variable. The part
  of the netCDF variable to write is specified by giving a corner (`start`) and
@@ -218,7 +218,7 @@ Option2 Method calls of put_var()/get_var()
     # The above line is equivalent to var[10:20, 0:50] = buff
 
 
-Reading from variable
+Reading from a variable
 ----------------------
 
  Symmetrically, users can use two options with different syntaxes to retrieve
@@ -228,10 +228,10 @@ Reading from variable
  .. code-block:: Python
 
     var = f.variables['var']
-    # Option1 Indexer: read the topleft 10*10 corner from variable var
+    # Option 1 Indexer: read the top-left 10*10 corner from variable var
     buf = var[:10, :10]
 
-    # Option2 Method Call: equivalent to var[10:20, 0:50]
+    # Option 2 Method Call: equivalent to var[10:20, 0:50]
     buf = var.get_var_all(start = [10, 0], count = [10, 50])
 
  Similarly, :meth:`Variable.get_var` takes the same set of optional arguments

docs/source/tutorial/datatypes.rst

@@ -26,7 +26,7 @@ NetCDF Variable Data Types
       +-------+----------------+-------+----------------------------------------+---------------------+
 
 
- New data types supported in CDF-5 format:
+ Additional data types supported in CDF-5 format:
 
       +---------------------+----------------+-------+----------------------------------------+---------------------+
       | Type                | C #define      | Bits  | Intent of use                          | Numpy Equivalent    |

docs/source/tutorial/read_write.rst

@@ -6,10 +6,10 @@ Parallel Read and Write
 NumPy Slicing Syntax
 --------------------------------------
 
- PnetCDF-python datasets re-use the numpy slicing syntax to read and write to
- the file. Slice specifications are translated directly to PnetCDF “start,
- count, stride” selections, and are a fast and efficient way to access data in
- the file. The following slicing arguments are recognized:
+ PnetCDF-python datasets re-use the ``numpy`` slicing syntax to read and write
+ to the file. Slice specifications are translated directly to PnetCDF-C style
+ of subarray selection, i.e. using index arrays of “start, count, stride”.
+ The following slicing arguments are recognized:
 
  - Indices (var[1,5])
  - Slices (i.e. [:] or [0:10])
@@ -29,7 +29,7 @@ NumPy Slicing Syntax
     # put values to the entire variable
     var[:] = buff
 
-    # read the topleft 10*10 corner from variable var
+    # read the top-left 10*10 corner from variable var
     print(var[:10, :10])