Merge 9f90bf6 into b61952e

.readthedocs.yml

@@ -0,0 +1,18 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the doc/ directory with Sphinx
+sphinx:
+    configuration: doc/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: all
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+    version: 3
+    # system_packages: true

LICENSE.rst

@@ -1,4 +1,4 @@
-Copyright (c) 2014-2017, DESI Collaboration <desi-data@desi.lbl.gov>
+Copyright (c) 2014-2019, DESI Collaboration <desi-data@desi.lbl.gov>
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,

doc/conf.py

@@ -62,7 +62,7 @@
 
 # General information about the project.
 project = u'desiutil'
-copyright = u'2014-2018, DESI Collaboration'
+copyright = u'2014-2019, DESI Collaboration'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

doc/index.rst

@@ -17,23 +17,25 @@ Required Dependencies
 
 These packages must be installed for desiutil to work properly:
 
-* `pyyaml <http://pyyaml.org/>`_
-* `astropy <http://www.astropy.org/>`_
+* `pyyaml <https://pyyaml.org/>`_
+* `requests <https://2.python-requests.org/en/master/>`_
+* `astropy <https://www.astropy.org/>`_
 
-  - This implies a dependency on `NumPy <http://www.numpy.org>`_
+  - This implies a dependency on `NumPy <https://numpy.org>`_
 
 Optional Dependencies
 +++++++++++++++++++++
 
 If you want to use the plotting utilities in :mod:`desiutil.plots`, you will
 need:
 
-* `matplotlib <http://matplotlib.org/>`_
+* `matplotlib <https://matplotlib.org/>`_
 * `healpy <https://healpy.readthedocs.io/en/latest/>`_
-* `basemap <http://matplotlib.org/basemap/>`_
+* `basemap <https://matplotlib.org/basemap/>`_
 
-  - Note that basemap's installation is non-trivial.  See the documentation
+  - Note that ``basemap``'s installation is non-trivial.  See the documentation
     linked to above.
+  - Also, ``basemap`` is currently deprecated.
 
 Contents
 ========

py/desiutil/bitmask.py

@@ -142,7 +142,7 @@ def __getitem__(self, bitname):
         return self._bits[bitname]
 
     def bitnum(self, bitname):
-        """Return bit number (int) for bitname (string).
+        """Return bit number (int) for this `bitname` (string).
 
         Parameters
         ----------
@@ -157,7 +157,7 @@ def bitnum(self, bitname):
         return self._bits[bitname].bitnum
 
     def bitname(self, bitnum):
-        """Return bit name (string) for this bitnum (integer).
+        """Return bit name (string) for this `bitnum` (integer).
 
         Parameters
         ----------

py/desiutil/brick.py

@@ -29,10 +29,6 @@ class Bricks(object):
     ----------
     bricksize : :class:`float`, optional
         Brick size in degrees.  Default 0.25 degrees.
-
-    Attributes
-    ----------
-    bricksize
     """
     def __init__(self, bricksize=0.25):
         # Brick row centers and edges

py/desiutil/depend.py

@@ -55,6 +55,8 @@
 ('foo', '3.4')
 
 """
+import sys
+import importlib
 #
 # default possible dependencies to check in add_dependencies()
 #
@@ -67,13 +69,21 @@
 
 
 def setdep(header, name, version):
-    '''
-    Set dependency version for code name.
+    '''Set dependency `version` for code `name`.
 
-    Args:
-        header : dict-like object to store dependencies
-        name : code name string
-        version : version string
+    Parameters
+    ----------
+    header : dict-like
+        A dict-like object, *e.g.* :class:`astropy.io.fits.Header`.
+    name : :class:`str`
+        Code name string.
+    version : :class:`str`
+        Code version string.
+
+    Raises
+    ------
+    IndexError
+        If there are more than 100 dependencies to track.
     '''
     for i in range(100):
         namekey = 'DEPNAM{:02d}'.format(i)
@@ -92,16 +102,24 @@ def setdep(header, name, version):
 
 
 def getdep(header, name):
-    '''
-    Get dependency version for code name.
-
-    Args:
-        header : dict-like object to store dependencies
-        name : code name string
-
-    Returns version string for name
+    '''Get dependency version for code `name`.
 
-    Raises KeyError if name not tracked in header
+    Parameters
+    ----------
+    header : dict-like
+        A dict-like object, *e.g.* :class:`astropy.io.fits.Header`.
+    name : :class:`str`
+        Code name string.
+
+    Returns
+    -------
+    :class:`str`
+        The version string for `name`.
+
+    Raises
+    ------
+    KeyError
+        If `name` not tracked in `header`.
     '''
     for i in range(100):
         namekey = 'DEPNAM{:02d}'.format(i)
@@ -116,8 +134,19 @@ def getdep(header, name):
 
 
 def hasdep(header, name):
-    '''
-    Returns ``True`` if version for name is tracked in header, otherwise ``False``.
+    '''Check if `name` is defined in `header`.
+
+    Parameters
+    ----------
+    header : dict-like
+        A dict-like object, *e.g.* :class:`astropy.io.fits.Header`.
+    name : :class:`str`
+        Code name string.
+
+    Returns
+    -------
+    :class:`bool`
+        ``True`` if version for `name` is tracked in `header`, otherwise ``False``.
     '''
     try:
         version = getdep(header, name)
@@ -127,7 +156,13 @@ def hasdep(header, name):
 
 
 def iterdep(header):
-    '''Returns iterator over (codename, version) tuples'''
+    '''Returns iterator over (codename, version) tuples.
+
+    Parameters
+    ----------
+    header : dict-like
+        A dict-like object, *e.g.* :class:`astropy.io.fits.Header`.
+    '''
     for i in range(100):
         namekey = 'DEPNAM{:02d}'.format(i)
         verkey = 'DEPVER{:02d}'.format(i)
@@ -141,25 +176,26 @@ def iterdep(header):
 
 
 def add_dependencies(header, module_names=None, long_python=False):
-    '''Adds DEPNAMnn, DEPVERnn keywords to header for imported modules
-
-    Args:
-        header : dict-like object, *e.g.* :class:`astropy.io.fits.Header`.
-
-    Options:
-        module_names : list of module names to check
-            if None, checks desiutil.depend.possible_dependencies
-        long_python : If ``True`` use the full, verbose ``sys.version``
-            string for the Python version.  Otherwise, use a short
-            version, *e.g.*, ``3.5.2``.
+    '''Adds ``DEPNAMnn``, ``DEPVERnn`` keywords to header for imported modules.
 
+    Parameters
+    ----------
+    header : dict-like
+        A dict-like object, *e.g.* :class:`astropy.io.fits.Header`.
+    module_names : :class:`list`, optional
+        List of of module names to check; if ``None``,
+        checks ``desiutil.depend.possible_dependencies``.
+    long_python : :class:`bool`, optional
+        If ``True`` use the full, verbose ``sys.version``
+        string for the Python version.  Otherwise, use a short
+        version, *e.g.*, ``3.5.2``.
+
+    Notes
+    -----
     Only adds the dependency keywords if the module has already been
-    previously loaded in this python session.  Uses module.__version__
-    if available, otherwise "unknown (/path/to/module/)".
+    previously loaded in this python session.  Uses ``module.__version__``
+    if available, otherwise ``unknown (/path/to/module/)``.
     '''
-    import sys
-    import importlib
-
     py_version = ".".join(map(str, sys.version_info[0:3]))
     if long_python:
         py_version = sys.version.replace('\n', ' ')