Merge pull request #141 from dstansby/cdf-docstring

Fix doc build

cdflib/__init__.py

@@ -1,50 +1,10 @@
 from pathlib import Path
 
 from . import cdfread, cdfwrite
+from .cdf_factory import CDF
+from .cdf_to_xarray import cdf_to_xarray
 from .epochs import CDFepoch as cdfepoch  # noqa: F401
+from .epochs_astropy import CDFAstropy as cdfastropy
+from .xarray_to_cdf import xarray_to_cdf
 
-# This function determines if we are reading or writing a file
-
-
-def CDF(path, cdf_spec=None, delete=False, validate=None, string_encoding='ascii'):
-    """
-    This is a wrapper function for the cdfread and cdfwrite modules.  If you specify a file that exists, it returns a CDF reading class.
-    If you specify a file that does not yet exist, one will be created and this function will return a CDF writing class.
-
-    Parameters:
-        path (str): The path to a cdf file that exists -or- to one you wish to create
-        cdf_spec (dict, optional): If you are writing a CDF file, this specifies general parameters about data is written.  See the cdfwrite class for more details.
-        delete (bool, optional): Delete the file if it exists and return immediately
-        validate (bool, optional):
-        string_encoding (str, optional): How strings are encoded in a CDF file that you are reading.  Another common encoding is 'utf-8'.
-
-    Returns:
-         A CDF object that can be used for reading a file (if it exists) or writing to a file (if it does not exist)
-
-    Note:
-        With this library, you cannot both read and write a file at the same time.  You need to choose one or the other!
-
-    Example:
-        >>> # Simply open an existing CDF file and get some data from a variable
-        >>> import cdflib
-        >>> cdf_file = cdflib.CDF('/path/to/existing/cdf_file.cdf')
-        >>> x = cdf_file.varget("NameOfVariable", startrec = 0, endrec = 150)
-
-    """
-    path = Path(path).resolve().expanduser()
-
-    if path.is_file():
-        if delete:
-            path.unlink()
-            return
-        else:
-            return cdfread.CDF(path, validate=validate, string_encoding=string_encoding)
-    else:
-        return cdfwrite.CDF(path, cdf_spec=cdf_spec, delete=delete)
-
-try:
-    from .cdf_to_xarray import cdf_to_xarray
-    from .epochs_astropy import CDFAstropy as cdfastropy
-    from .xarray_to_cdf import xarray_to_cdf
-except Exception:
-    pass
+__all__ = ['CDF', 'xarray_to_cdf', 'cdf_to_xarray']

cdflib/cdf_factory.py

@@ -0,0 +1,58 @@
+from pathlib import Path
+
+from . import cdfread, cdfwrite
+from .epochs import CDFepoch as cdfepoch  # noqa: F401
+
+
+# This function determines if we are reading or writing a file
+def CDF(path, cdf_spec=None, delete=False, validate=None,
+        string_encoding='ascii'):
+    """
+    A wrapper function for cdfread and cdfwrite modules.
+
+    If you specify a file that exists, it returns a CDF reading class.
+    If you specify a file that does not yet exist, one will be created and this
+    function will return a CDF writing class.
+
+    Parameters
+    ----------
+    path : str
+        The path to a cdf file that exists or to one you wish to create
+    cdf_spec : dict, optional
+        If you are writing a CDF file, this specifies general parameters about
+        data is written.  See the cdfwrite class for more details.
+    delete : bool, optional
+        Delete the file if it exists and return immediately.
+    validate : bool, optional
+    string_encoding : str, optional
+        How strings are encoded in a CDF file that you are reading.
+        Another common encoding is 'utf-8'.
+
+    Returns
+    -------
+    A CDF object that can be used for reading a file (if it exists) or writing
+    to a file (if it does not exist)
+
+    Notes
+    -----
+    With this library, you cannot both read and write a file at the same time.
+    You need to choose one or the other!
+
+    Examples
+    --------
+    Open an existing CDF file and get some data from a variable
+    >>> import cdflib
+    >>> cdf_file = cdflib.CDF('/path/to/existing/cdf_file.cdf')
+    >>> x = cdf_file.varget("NameOfVariable", startrec = 0, endrec = 150)
+
+    """
+    path = Path(path).resolve().expanduser()
+
+    if path.is_file():
+        if delete:
+            path.unlink()
+            return
+        else:
+            return cdfread.CDF(path, validate=validate, string_encoding=string_encoding)
+    else:
+        return cdfwrite.CDF(path, cdf_spec=cdf_spec, delete=delete)

cdflib/cdf_to_xarray.py

@@ -1,9 +1,10 @@
+import re
+
 import numpy as np
 import xarray as xr
-from cdflib import CDF
-from cdflib.epochs import CDFepoch as cdfepoch
-import re
 
+from cdflib.epochs import CDFepoch as cdfepoch
+from .cdf_factory import CDF
 
 ISTP_TO_XARRAY_ATTRS = {'FIELDNAM': 'standard_name',
                         'LABLAXIS': 'long_name',
@@ -21,7 +22,7 @@ def _find_xarray_plotting_values(var_att_dict):
     xarray_att_dict = {}
     if not var_att_dict:
         return xarray_att_dict
-    for key,value in var_att_dict.items():
+    for key, value in var_att_dict.items():
         if key in ISTP_TO_XARRAY_ATTRS:
             xarray_att_dict[ISTP_TO_XARRAY_ATTRS[key]] = value
     return xarray_att_dict
@@ -40,7 +41,7 @@ def _convert_cdf_time_types(data, atts, properties, to_datetime=False, to_unixti
 
     try:
         len(data)
-    except Exception as e:
+    except Exception:
         data = [data]
 
     if to_datetime and to_unixtime:
@@ -653,7 +654,7 @@ def cdf_to_xarray(filename, to_datetime=False, to_unixtime=False, fillval_to_nan
         >>> print(thg_data)
 
     Processing Steps:
-        1. For each variable in the CDF file - 
+        1. For each variable in the CDF file -
             1. Determine the name of the dimension that spans the data "records".  This can be done in a few ways -
                 1. Check if the variable itself might be a dimension
                 2. The DEPEND_0 likely points to the approrpiate dimensions

cdflib/xarray_to_cdf.py

@@ -1,9 +1,12 @@
 import os
-import numpy as np
+import re
 from datetime import datetime
+
+import numpy as np
+
 from cdflib.epochs import CDFepoch as cdfepoch
-from cdflib import CDF
-import re
+from .cdf_factory import CDF
+
 
 def _dtype_to_cdf_type(var):
 
@@ -626,7 +629,7 @@ def xarray_to_cdf(xarray_dataset, file_name, from_unixtime=False, from_datetime=
 
     if istp:
         # This creates a list of suspected or confirmed label variables
-        label_vars = _label_checker(dataset)
+        _label_checker(dataset)
 
         # This creates a list of suspected or confirmed dimension variables
         dim_vars = _dimension_checker(dataset)

doc/conf.py

@@ -13,6 +13,7 @@
 #
 import os
 import sys
+
 sys.path.insert(0, os.path.abspath("."))
 sys.path.insert(0, os.path.abspath("../"))
 sys.path.insert(0, os.path.abspath('../..'))
@@ -37,7 +38,9 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.napoleon']
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.viewcode',
+              'sphinx.ext.napoleon']
 
 numpydoc_class_members_toctree = False
 
@@ -161,4 +164,4 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/3': None}
-#autodoc_mock_imports = ['xarray', 'astropy']
+#autodoc_mock_imports = ['xarray', 'astropy']

doc/development.rst

@@ -0,0 +1,11 @@
+Developing cdflib
+=================
+
+Documentation
+-------------
+To build the documentation you will need to install the documentation
+requirements using::
+
+  pip install .[docs]
+
+This will install cdflib and all the packages need to make the documenation.

doc/index.rst

@@ -19,13 +19,9 @@ cdflib requires python 3 and numpy. To install run
    :caption: Contents:
 
    introduction
-   modules/CDF function
-   modules/cdfread
-   modules/cdfwrite
-   modules/epochs
-   modules/epochs_astropy
-   modules/cdf_to_xarray
-   modules/xarray_to_cdf
+   modules/cdflib
+   modules/xarray
+   development
 
 
 

doc/modules/cdflib.rst

@@ -0,0 +1,4 @@
+CDF
+===
+
+.. autofunction:: cdflib.CDF

doc/modules/xarray.rst

@@ -0,0 +1,13 @@
+Working with XArray
+===================
+
+There are two functions for working with XArray DataSets, one for converting
+a CDF to a DataSet, and one for going the other way.
+
+These will attempt to determine any
+`ISTP Compliance <https://spdf.gsfc.nasa.gov/istp_guide/istp_guide.html>`_ within
+the file, and incorporate that into the Dataset object.
+
+.. autofunction:: cdflib.cdf_to_xarray
+
+.. autofunction:: cdflib.xarray_to_cdf