Update to numpydoc standard

doc/.gitignore

@@ -0,0 +1,10 @@
+# Doxygen products
+html
+xml
+*.tag
+*.inc
+doxygen.conf
+
+# Sphinx products
+_build
+py-api

doc/conf.py

@@ -0,0 +1,13 @@
+"""Sphinx configuration file for an LSST stack package.
+
+This configuration only affects single-package Sphinx documentation builds.
+"""
+
+from documenteer.sphinxconfig.stackconf import build_package_configs
+import lsst.daf.base
+
+
+_g = globals()
+_g.update(build_package_configs(
+    project_name='daf_base',
+    version=lsst.daf.base.version.__version__))

doc/index.rst

@@ -0,0 +1,12 @@
+##############################
+daf_base documentation preview
+##############################
+
+.. This page is for local development only. It isn't published to pipelines.lsst.io.
+
+.. Link the index pages of package and module documentation directions (listed in manifest.yaml).
+
+.. toctree::
+   :maxdepth: 1
+
+   lsst.daf.base/index

doc/lsst.daf.base/index.rst

@@ -0,0 +1,36 @@
+.. py:currentmodule:: lsst.daf.base
+
+.. _lsst.daf.base:
+
+#############
+lsst.daf.base
+#############
+
+.. Paragraph that describes what this Python module does and links to related modules and frameworks.
+
+.. .. _lsst.daf.base-using:
+
+.. Using lsst.daf.base
+.. ==================
+
+.. toctree linking to topics related to using the module's APIs.
+
+.. .. toctree::
+..    :maxdepth: 1
+
+.. _lsst.daf.base-contributing:
+
+Contributing
+============
+
+``lsst.daf.base`` is developed at https://github.com/lsst/daf_base.
+You can find Jira issues for this module under the `daf_base <https://jira.lsstcorp.org/issues/?jql=project%20%3D%20DM%20AND%20component%20%3D%20daf_base>`_ component.
+
+.. _lsst.daf.base-pyapi:
+
+Python API reference
+====================
+
+.. automodapi:: lsst.daf.base
+   :no-main-docstr:
+   :no-inheritance-diagram:

doc/manifest.yaml

@@ -0,0 +1,12 @@
+# Documentation manifest.
+
+# List of names of Python modules in this package.
+# For each module there is a corresponding module doc subdirectory.
+modules:
+  - "lsst.daf.base"
+
+# Name of the static content directories (subdirectories of `_static`).
+# Static content directories are usually named after the package.
+# Most packages do not need a static content directory (leave commented out).
+# statics:
+#   - "_static/example"

python/lsst/daf/base/dateTime/dateTimeContinued.py

@@ -35,7 +35,15 @@ class DateTime:
     def toPython(self, timescale=None):
         """Convert a DateTime to Python's datetime
 
-        @param timescale  Timescale for resultant datetime
+        Parameters
+        ----------
+        timescale : `dateTime.DateTime.Timescale`, optional
+            Timescale for resultant datetime.
+
+        Returns
+        -------
+        datetime : `datetime.datetime`
+            The resultant Python `datetime.datetime` object.
         """
         import datetime
         nsecs = self.nsecs(timescale) if timescale is not None else self.nsecs()

python/lsst/daf/base/propertyContainer/propertyContainerContinued.py

@@ -53,12 +53,16 @@ def getPropertySetState(container, asLists=False):
     state : `list` of `tuple` or `list` of `list`
         The state, as a list of tuples (or lists), each of which contains
         the following 3 items:
-        - name (a `str`): the name of the item
-        - elementTypeName (a `str`): the suffix of a ``setX`` method name
+
+        name (a `str`)
+            the name of the item
+        elementTypeName (a `str`)
+            the suffix of a ``setX`` method name
             which is appropriate for the data type. For example integer
             data has ``elementTypeName="Int"` which corresponds to
             the ``setInt`` method.
-        - value: the data for the item, in a form compatible
+        value
+            the data for the item, in a form compatible
             with the set method named by ``elementTypeName``
     """
     names = container.names(topLevelOnly=True)
@@ -84,14 +88,18 @@ def getPropertyListState(container, asLists=False):
     state : `list` of `tuple` or `list` of `list`
         The state, as a list of tuples (or lists), each of which contains
         the following 4 items:
-        - name (a `str`): the name of the item
-        - elementTypeName (a `str`): the suffix of a ``setX`` method name
+
+        name (a `str`):
+            the name of the item
+        elementTypeName (a `str`):
+            the suffix of a ``setX`` method name
             which is appropriate for the data type. For example integer
             data has ``elementTypeName="Int"` which corresponds to
             the ``setInt`` method.
-        - value: the data for the item, in a form compatible
+        value
+            the data for the item, in a form compatible
             with the set method named by ``elementTypeName``
-        - comment (a `str`): the comment. This item is only present
+        comment (a `str`): the comment. This item is only present
             if ``container`` is a PropertyList.
     """
     sequence = list if asLists else tuple
@@ -141,7 +149,15 @@ class ReturnStyle(enum.Enum):
 
 
 def _propertyContainerElementTypeName(container, name):
-    """Return name of the type of a particular element"""
+    """Return name of the type of a particular element
+
+    Parameters
+    ----------
+    container : `lsst.daf.base.PropertySet` or `lsst.daf.base.PropertyList`
+        Container including the element
+    name : `str`
+        Name of element
+    """
     try:
         t = container.typeOf(name)
     except LookupError as e:
@@ -223,7 +239,22 @@ def _guessIntegerType(container, name, value):
     If there is no pre-existing value we have to decide what to do. For now
     we pick Int if the value is less than maxsize.
 
-    Returns None if the value supplied is a bool or not an integral value.
+    Parameters
+    ----------
+    container : `lsst.daf.base.PropertySet` or `lsst.daf.base.PropertyList`
+        Container from which to get the value
+
+    name : `str`
+        Name of item
+
+    value : `object`
+        Value to be assigned a type
+
+    Returns
+    -------
+    useType : `str` or none
+        Type to use for the supplied value. `None` if the input is
+        `bool` or a non-integral value.
     """
     useType = None
     maxInt = 2147483647
@@ -266,7 +297,8 @@ def _guessIntegerType(container, name, value):
 
 
 def _propertyContainerSet(container, name, value, typeMenu, *args):
-    """Set a single Python value of unknown type"""
+    """Set a single Python value of unknown type
+    """
     if hasattr(value, "__iter__") and not isinstance(value, (str, PropertySet, PropertyList)):
         exemplar = value[0]
     else:
@@ -288,7 +320,8 @@ def _propertyContainerSet(container, name, value, typeMenu, *args):
 
 
 def _propertyContainerAdd(container, name, value, typeMenu, *args):
-    """Add a single Python value of unknown type"""
+    """Add a single Python value of unknown type
+    """
     if hasattr(value, "__iter__"):
         exemplar = value[0]
     else:
@@ -358,7 +391,7 @@ def get(self, name, default=None):
 
         Parameters
         ----------
-        name : ``str``
+        name : `str`
             Name of item
         default : `object`, optional
             Default value to use if the named item is not present.

python/lsst/daf/base/yaml.py

@@ -65,7 +65,8 @@ def dt_representer(dumper, data):
 
 def pl_representer(dumper, data):
     """Represent an lsst.daf.base.PropertyList as an ordered sequence of
-    name/type/value/comment lists)"""
+    name/type/value/comment lists)
+    """
     # Turn the tuples into lists for cleaner representation in yaml
     result = getPropertyListState(data, asLists=True)
     return dumper.represent_sequence('lsst.daf.base.PropertyList', result,
@@ -78,7 +79,8 @@ def pl_representer(dumper, data):
 
 def ps_representer(dumper, data):
     """Represent an lsst.daf.base.PropertySet as a mapping from names to
-    type/value pairs."""
+    type/value pairs.
+    """
     # Turn the tuples into lists for cleaner representation in yaml
     result = getPropertySetState(data, asLists=True)
     return dumper.represent_sequence('lsst.daf.base.PropertySet', result,
@@ -95,14 +97,16 @@ def ps_representer(dumper, data):
 
 def dt_constructor(loader, node):
     """Construct an lsst.daf.base.DateTime from an ISO8601-formatted string in
-    TAI"""
+    TAI
+    """
     dt = loader.construct_scalar(node)
     return DateTime(str(dt), DateTime.TAI)
 
 
 def pl_constructor(loader, node):
     """Construct an lsst.daf.base.PropertyList from a YAML pickle-like
-    structure."""
+    structure.
+    """
     pl = PropertyList()
     yield pl
     state = loader.construct_sequence(node, deep=True)
@@ -111,7 +115,8 @@ def pl_constructor(loader, node):
 
 def ps_constructor(loader, node):
     """Construct an lsst.daf.base.PropertyList from a YAML pickle-like
-    structure."""
+    structure.
+    """
     ps = PropertySet()
     yield ps
     state = loader.construct_sequence(node, deep=True)

tests/test_PropertyList.py

@@ -30,12 +30,14 @@
 
 class FloatSubClass(float):
     """Intended to be something like numpy.float64, without introducing a
-    dependency on numpy"""
+    dependency on numpy
+    """
     pass
 
 
 class PropertyListTestCase(unittest.TestCase):
-    """A test case for PropertyList."""
+    """A test case for PropertyList.
+    """
 
     def testConstruct(self):
         apl = dafBase.PropertyList()

tests/test_PropertySet_2.py

@@ -32,7 +32,8 @@
 
 
 class PropertySetTestCase(unittest.TestCase):
-    """A test case for PropertySet."""
+    """A test case for PropertySet.
+    """
 
     def testConstruct(self):
         ps = dafBase.PropertySet()
@@ -308,7 +309,8 @@ def testCopy(self):
 
 
 class FlatTestCase(unittest.TestCase):
-    """A test case for flattened PropertySets."""
+    """A test case for flattened PropertySets.
+    """
 
     def testConstruct(self):
         ps = dafBase.PropertySet(flat=True)
@@ -750,7 +752,8 @@ def testvariousThrows(self):
         ps.remove("int.sub")
 
     def testIntegerRanges(self):
-        """Test that the ranges of the various integer types is as expected"""
+        """Test that the ranges of the various integer types is as expected
+        """
         ps = dafBase.PropertySet()
         minI32 = -2**31
         maxI32 = 2**31 - 1

tests/test_dateTime.py

@@ -31,7 +31,8 @@
 
 
 class DateTimeTestCase(unittest.TestCase):
-    """A test case for DateTime."""
+    """A test case for DateTime.
+    """
 
     def setUp(self):
         self.timeScales = (DateTime.TAI, DateTime.TT, DateTime.UTC)
@@ -114,7 +115,8 @@ def testIsoEpoch(self):
         self.assertEqual(ts.toString(ts.UTC), "1970-01-01T00:00:00.000000000Z")
 
     def testIsoUTCBasic(self):
-        """Test basic ISO string input and output of UTC dates"""
+        """Test basic ISO string input and output of UTC dates
+        """
         for dateSep in ("-", ""):  # "-" date separator is optional
             for timeSep in (":", ""):  # ":" time separator is optional
                 for decPt in (".", ","):  # "." or "," may be used as decimal point
@@ -126,7 +128,8 @@ def testIsoUTCBasic(self):
                     self.assertEqual(ts.toString(ts.UTC), "2009-04-02T07:26:39.314159265Z")
 
     def testIsoNonUTCBasics(self):
-        """Test basic ISO string input and output of TAI and TT dates"""
+        """Test basic ISO string input and output of TAI and TT dates
+        """
         for scale in (DateTime.TAI, DateTime.TT):
             for dateSep in ("-", ""):  # "-" date separator is optional
                 for timeSep in (":", ""):  # ":" time separator is optional

tests/test_yaml.py

@@ -84,7 +84,8 @@ def testYamlPL(self):
         self.assertEqual(apl, apl2)
 
     def testYamlNest(self):
-        """Test nested property sets"""
+        """Test nested property sets
+        """
         ps = lsst.daf.base.PropertySet()
         ps.setBool("bool", True)
         ps.setShort("short", 42)
@@ -124,7 +125,8 @@ def testYamlDateTime(self):
         self.assertEqual(ts, ts2)
 
     def testLoader(self):
-        """Test loading of reference YAML files"""
+        """Test loading of reference YAML files
+        """
         # Old and new serialization of a propertyList
         with open(os.path.join(TESTDIR, "data", "fitsheader-tuple.yaml")) as fd:
             old = yaml.load(fd, Loader=yaml.Loader)