Merge pull request #56 from wkliao/doc_v4

docs: polishing

Author: wkliao

docs/source/api/attribute_api.rst

@@ -1,8 +1,24 @@
 ===========
-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).
+In `object-oriented programming <https://en.wikipedia.org/wiki/Object-oriented_programming>`_,
+a class contains fields (state variables containing data) and methods
+(subroutines or procedures defining the object's behavior in code). ``Fields``
+may also be known as members, attributes, or properties. To avoid confusion
+with NetCDF's terminology of ``attribute``, this document uses `field` to refer
+to a class's state variable.
+
+NetCDF attributes are small, supplementary metadata that annotates variables or
+files.  NetCDF attribute is not a Python class by itself. Instead, it is a
+field of python dictionary in class :class:`pnetcdf.File` and class
+:class:`pnetcdf.Variable`.  Their data types can be any allowed by the classic
+NetCDF file formats.  The most common data type is `text` for annotation
+purpose.  NetCDF attributes can be created, accessed, and manipulated using
+python dictionary-like syntax.  An attribute can be associated to a file,
+referred to as ``golbal attribute``, as well as to individual variables,
+referred to as ``variable's attribute``.  Pythonic interfaces for accessing
+attributes are is provided both in class :class:`pnetcdf.File` (for global
+attributes) and class :class:`pnetcdf.Variable` (for variable attributes).
+Example programs are `examples/global_attribute.py` and `examples/put_var.py`.
+

docs/source/api/dimension_api.rst

@@ -1,30 +1,32 @@
 ==============
-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
    :exclude-members: name, size
 
-Read-only Python Attributes of Dimension Class
- The following class members are read-only and should not be modified by the
+Read-only python fields of class :class:`pnetcdf.Dimension`
+ The following class fields are read-only and should not be modified by the
  user.
 
  .. attribute:: name
 
-    String name of Dimension instance. This class member is read-only and
+    String name of Dimension instance. This class field is read-only and
     should not be modified by the user. To rename a dimension, use
     :meth:`File.rename_dim` method.
 
     **Type:** `str`
 
  .. 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,
@@ -17,21 +17,21 @@ relations among data fields stored in a netCDF file.
     inq_header_size, inq_put_size, inq_header_extent, inq_nreqs
    :exclude-members: dimensions, variables, file_format, indep_mode, path
 
-Read-only Python Attributes of File Class
- The following class members are read-only and should not be modified by the
+Read-only python fields of class :class:`pnetcdf.File`
+ The following class fields are read-only and should not be modified by the
  user.
 
    .. 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,7 +1,10 @@
 ================
-Utility Functions
+Other pnetcdf class methods
 ================
 
+   PnetCDF class methods listed below are not associated with particular
+   instances of ``File`` or ``Variable``.
+
 .. autofunction:: pnetcdf::libver
 .. autofunction:: pnetcdf::strerror
 .. autofunction:: pnetcdf::strerrno

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,
@@ -18,8 +20,8 @@ indexer-style (numpy-like) syntax.
     chartostring
 
 
-Read-only Python Attributes of Variable Class
-    The following class members are read-only and should not be modified
+Read-only python fields of class :class:`pnetcdf.Variable`
+    The following class fields are read-only and should not be modified
     directly by the user.
 
     .. attribute:: name

docs/copyright.rst renamed to 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,16 +33,17 @@ 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
-   :caption: Copyright Statement
+   :maxdepth: 1
+   :caption: Copyright
 
    copyright