Merge pull request #31 from DLHub-Argonne/improve_docs

WIP: Improve docs

dlhub_sdk/models/__init__.py

@@ -1,3 +1,5 @@
+"""This module contains tools for describing objects being published to DLHub."""
+
 from itertools import zip_longest
 from datetime import datetime
 from six import string_types
@@ -21,7 +23,7 @@ class BaseMetadataModel:
     Covers information that goes in the :code:`datacite` block of the metadata file and
     some of the DLHub block.
 
-    ## Using a MetadataModel
+    --> Using a MetadataModel <--
 
     There are many kinds of MetadataModel classes that each describe a different kind of object.
     Each of these different types are created using the :code:`create_model` operation

dlhub_sdk/models/datasets.py

@@ -1,6 +1,3 @@
-import os
-
-from collections import OrderedDict
 import pandas as pd
 
 from dlhub_sdk.models import BaseMetadataModel
@@ -31,7 +28,7 @@ class TabularDataset(Dataset):
     column names with descriptions of the data provided.
     
     This class is compatible with any data format readable by the Pandas
-    library. See the list of `read functions in Pandas<https://pandas.pydata.org/pandas-docs/stable/io.html>`_"""
+    library. See the list of `read functions in Pandas <https://pandas.pydata.org/pandas-docs/stable/io.html>`_"""
 
     @classmethod
     def create_model(cls, path, format="csv", read_kwargs=None):
@@ -55,12 +52,12 @@ def load_dataset(self, path, format, **kwargs):
         """Load in a dataset to get some high-level descriptions of it
 
         Args:
-        path (string): Path to dataset
-        format (string): Format of the dataset. We support all of the 
-            read operations of Pandas (e.g., read_csv). Provide the format
-            of your dataset as the suffix for the Pandas read command (e.g.,
-            "csv" for "read_csv").
-        **kwargs (dict): arguments for the Pandas read function
+            path (string): Path to dataset
+            format (string): Format of the dataset. We support all of the
+                read operations of Pandas (e.g., read_csv). Provide the format
+                of your dataset as the suffix for the Pandas read command (e.g.,
+                "csv" for "read_csv").
+            **kwargs (dict): arguments for the Pandas read function
         """
 
         # Add the data as the path of interest

dlhub_sdk/models/servables/__init__.py

@@ -86,13 +86,14 @@ def to_dict(self, simplify_paths=False, save_class_data=False):
     def add_requirement(self, library, version=None):
         """Add a required Python library.
 
-        The name of the library should be either the name on PyPI, or a link to the
+        The name of the library should be either the name on PyPI, or a URL for the git repository
+        holding the code (e.g., ``git+https://github.com/DLHub-Argonne/dlhub_sdk.git``)
 
         Args:
             library (string): Name of library
             version (string): Required version. 'latest' to use the most recent version on PyPi (if
-            available). 'detect' will attempt to find the version of the library installed on
-                the computer running this software.
+                available). 'detect' will attempt to find the version of the library installed on
+                the computer running this software. Default is ``None``
         """
 
         # Attempt to determine the version automatically

dlhub_sdk/models/servables/python.py

@@ -151,7 +151,7 @@ def from_function_pointer(cls, f, autobatch=False, function_kwargs=None):
 
         Args:
             f (object): A function pointer
-            autobatch (bool): Whether to run function on an interable of entries
+            autobatch (bool): Whether to run function on an iterable of entries
             function_kwargs (dict): Any default options for this function
         """
         return cls.create_model(f.__module__, f.__name__, autobatch, function_kwargs)

dlhub_sdk/models/servables/tensorflow.py

@@ -1,5 +1,5 @@
 from dlhub_sdk.utils.types import compose_argument_block, simplify_numpy_dtype
-from . import BaseServableModel
+from dlhub_sdk.models.servables import BaseServableModel
 import tensorflow as tf
 import numpy as np
 
@@ -109,8 +109,10 @@ def create_model(cls, export_directory):
 
         # Check if there is a run method
         if 'run' not in output['servable']['methods']:
-            raise ValueError('There is no default servable for this model.'
-                             ' DLHub currently requires ones')
+            raise ValueError('There is no default servable for this model.\n'
+                             ' Make sure to use '
+                             'tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY '
+                             'when saving model.')
 
         # Add tensorflow version and files
         output.add_requirement('tensorflow', tf.__version__)

docs/argument-types.rst

@@ -0,0 +1,115 @@
+Argument Types
+==============
+
+DLHub supports many types of data as inputs and outputs to servables.
+In this part of the guide, we describe what these types are and how to define them when describing an interface.
+A full listing of the types is maintained in the `DLHub schemas repository <https://github.com/DLHub-Argonne/dlhub_schemas/blob/master/schemas/servable/argument_type.json>`_.
+A utility for creating type definitions can also be found in the `DLHub SDK <source/dlhub_sdk.utils.html#module-dlhub_sdk.utils.types>`_.
+
+float, integer, number, complex
+-----------------------------------------------
+
+There are a variety of ways to express numerical values in DLHub interfaces:
+- ``number`` implies any real numerical value and implies there is limitation of the data being a float or integer.
+- ``float`` and ``integer`` are available if it is necessary to ensure the values are stored as floats or integers.
+- The ``complex`` argument type is used for complex numbers
+
+string
+------
+
+Used for any string values.
+
+boolean
+-------
+
+Used for Boolean values.
+
+timedelta, datetime
+-------------------
+
+These data types define values associated with time.
+``timedelta`` and ``datetime`` represent a length of time and a specific time, respectively.
+
+python object
+-------------
+
+The ``python object`` type is used for data that cannot be expressed by other types.
+The only required argument for the ``python object`` is the Python type of the
+object by listed the Python class as ``python_type`` keyword.
+For example, a Pandas Dataframe would be expressed as:
+
+.. code-block:: json
+
+    {
+        "type": "python object",
+        "python_type": "pandas.DataFrame"
+    }
+
+ndarray
+-------
+
+``ndarray`` values are matrices.
+It is required to specify the shape using the ``shape`` keyword, which takes a list of integers are ``None`` values.
+The ``null`` values in a shape definition represent that the dimension can take on any size.
+The type of each value in the array can be defined using the ``item_type`` keyword, which takes a type definition as its only argument.
+For example, an ``Nx3`` array of integers can be represented by:
+
+.. code-block:: json
+
+   {
+      "type": "ndarray",
+      "item_type": {"type": "integer"},
+      "shape": [null, 3]
+   }
+
+list
+----
+
+List types define an ordered collection of indefinite length of all the same type of items.
+Only the item type need be defined using the ``item_type`` keyword, which requires an argument type as its value.
+For example, a list of 1D ``ndarray`` would be:
+
+.. code-block:: json
+
+    {
+        "type": "list",
+        "item_type": {
+            "type": "ndarray",
+            "shape": [null]
+        }
+    }
+
+tuple
+-----
+
+Tuple types define an ordered collection of known length where each member can be a different type.
+The item type of each member and, thereby, the length must be defined using the ``member_types`` keyword.
+A tuple of a integer, float, and list of strings would be:
+
+.. code-block:: json
+
+    {
+        "type": "tuple",
+        "element_types": [
+            {"type": "integer"},
+            {"type": "float"},
+            {"type": "list", "item_type": "string"}
+        ]
+    }
+
+dict
+----
+
+The ``dict`` argument type is used for dictionary objects.
+The data type requires the names and types of each key to be defined in the ``properties`` keyword.
+For example, a dictionary with key "x" mapped to an integer and "y" mapped to a float would be:
+
+.. code-block:: json
+
+    {
+        "type": "dict",
+        "properties": {
+            "x": {"type": "integer"},
+            "y": {"type": "float"}
+        }
+    }

docs/conf.py

@@ -22,6 +22,7 @@
 # sys.path.insert(0, os.path.abspath('.'))
 import os
 import sys
+from dlhub_sdk.version import __version__
 sys.path.insert(0, os.path.abspath('.'))
 sys.path.insert(0, os.path.abspath('../'))
 
@@ -68,9 +69,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.1.0'
+version = __version__
 # The full version, including alpha/beta/rc tags.
-release = '0.1.0'
+release = __version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -124,6 +125,8 @@
     ]
 }
 
+html_favicon = 'img/favicon.ico'
+
 
 # -- Options for HTMLHelp output ------------------------------------------
 

docs/index.rst

@@ -18,11 +18,12 @@ Source Code: https://github.com/DLHub-Argonne/dlhub_cli
    :caption: Contents:
 
    quickstart
+   servable-publication
+   servable-types
+   argument-types
    source/modules
 
 
-
-
 Indices and tables
 ==================
 

docs/quickstart.rst

@@ -17,16 +17,16 @@ Installation using Pip
 ^^^^^^^^^^^^^^^^^^^^^^
 
 While ``pip`` and ``pip3`` can be used to install the CLI we suggest the following approach
-for reliable installation when many Python environments are avaialble.::
+for reliable installation when many Python environments are available.::
 
      $ python3 -m pip install dlhub_sdk
 
-     (to update a previously installed parsl to a newer version, use: python3 -m pip install -U dlhub_sdk)
+ To update a previously installed dlhub_sdk to a newer version, use: ``python3 -m pip install -U dlhub_sdk)``
 
 
 Installation using Conda
 ^^^^^^^^^^^^^^^^^^^^^^^^
-1. Install Conda and setup python3.6 following the instructions `here <https://conda.io/docs/user-guide/install/macos.html>`_::
+1. Install Conda and setup python3.6 following the instructions `here <https://conda.io/docs/user-guide/install>`_::
 
      $ conda create --name dlhub_py36 python=3.6
      $ source activate dlhub_py36
@@ -35,7 +35,7 @@ Installation using Conda
 
      $ python3 -m pip install dlhub_sdk
 
-     (to update a previously installed the cli to a newer version, use: python3 -m pip install -U dlhub_sdk)
+     (to update a previously installed DLHub SDK to a newer version, use: python3 -m pip install -U dlhub_sdk)
 
 For Developers
 --------------