Merged in docs (pull request #38)

Docs

docs/source/conf.py

@@ -55,9 +55,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = 'v0.0.1'
+version = 'v0.1'
 # The full version, including alpha/beta/rc tags.
-release = 'v0.0.1'
+release = 'v0.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/example.rst

@@ -3,7 +3,7 @@
 Examples
 ===========
 
-The following examples will reference variables that may not be defined within the block they are used. For 
+The following examples will reference variables that may not be defined within the block they are used. For
 clarity, we define them here.
 
 .. code-block:: python
@@ -14,13 +14,13 @@ clarity, we define them here.
     ephys_data = np.random.rand(data_len)
     ephys_timestamps = np.arange(data_len) / rate
     spatial_timestamps = ephys_timestamps[::10]
-    spatial_data = np.cumsum(sps.norm.rvs(size=(2,len(spatial_timestamps))), axis=-1).T 
+    spatial_data = np.cumsum(sps.norm.rvs(size=(2,len(spatial_timestamps))), axis=-1).T
 
 Creating and Writing NWB files
 -----------------------------------------------------
 
 When creating an NWB file, the first step is to create the :py:class:`~pynwb.ui.file.NWBFile`. The first
-argument is the name of the NWB file, and the second argument is a brief description of the dataset. 
+argument is the name of the NWB file, and the second argument is a brief description of the dataset.
 
 .. code-block:: python
 
@@ -55,7 +55,7 @@ Creating Electrode Groups
 -----------------------------------------------------
 
 Electrode groups (i.e. experimentally relevant groupings of channels) are represented by :py:class:`~pynwb.ui.ephys.ElectrodeGroup` objects. To create
-an electrode group, you can use the :py:class:`~pynwb.ui.file.NWBFile` instance method :py:func:`~pynwb.ui.file.NWBFile.create_electrode_group`. 
+an electrode group, you can use the :py:class:`~pynwb.ui.file.NWBFile` instance method :py:func:`~pynwb.ui.file.NWBFile.create_electrode_group`.
 
 .. code-block:: python
 
@@ -65,7 +65,7 @@ Creating TimeSeries
 -----------------------------------------------------
 
 TimeSeries objects can be created in two ways. The first way is by instantiating :ref:`timeseries_overview` objects directly and then adding them to
-the :ref:`file_overview` using the instance method :py:func:`~pynwb.ui.file.NWBFile.add_raw_timeseries`. The second way is by calling the :py:class:`~pynwb.ui.file.NWBFile` 
+the :ref:`file_overview` using the instance method :py:func:`~pynwb.ui.file.NWBFile.add_raw_timeseries`. The second way is by calling the :py:class:`~pynwb.ui.file.NWBFile`
 instance method :py:func:`~pynwb.ui.file.NWBFile.create_timeseries`. This first example will demonstrate instatiating two different
 types of :ref:`timeseries_overview` objects directly, and adding them with :py:func:`~pynwb.ui.file.NWBFile.add_raw_timeseries`.
 
@@ -93,3 +93,73 @@ types of :ref:`timeseries_overview` objects directly, and adding them with :py:f
                                comments="This data was generated with numpy, using 1234 as the seed",
                                description="This 2D Brownian process generated with numpy.cumsum(scipy.stats.norm.rvs(size=(2,len(timestamps))), axis=-1).T")
     f.add_raw_timeseries(spatial_ts, [ep1, ep2])
+
+Using Extensions
+-----------------------------------------------------
+
+The NWB file format supports extending existing data types (See <create_link> for more details on creating extensions).
+Extensions must be registered with PyNWB to be used for reading and writing of custom neurodata types.
+
+The following code demonstrates how to load custom namespaces.
+
+.. code-block:: python
+
+    from pynwb import load_namespaces
+    namespace_path = 'my_namespace.yaml'
+    load_namespaces(namespace_path)
+
+*NOTE*: This will register all namespaces defined in the file ``'my_namespace.yaml'``.
+
+To read and write custom data, corresponding :py:class:`~pynwb.core.NWBContainer` classes must be associated with their respective specifications.
+:py:class:`~pynwb.core.NWBContainer` classes are associated with their respective specification using the decorator :py:func:`~pynwb.register_class`.
+
+The following code demonstrates how to associate a specification with the :py:class:`~pynwb.core.NWBContainer` class that represents it.
+
+.. code-block:: python
+
+    from pynwb import register_class
+    @register_class('my_namespace', 'MyExtension')
+    class MyExtensionContainer(NWBContainer):
+        ...
+
+:py:func:`~pynwb.register_class` can also be used as a function.
+
+.. code-block:: python
+
+    from pynwb import register_class
+    class MyExtensionContainer(NWBContainer):
+        ...
+    register_class('my_namespace', 'MyExtension', MyExtensionContainer)
+
+If your :py:class:`~pynwb.core.NWBContainer` extension requires custom mapping of the :py:class:`~pynwb.core.NWBContainer` class for reading and writing, you will need
+to implement and register a custom :py:class:`~form.build.map.ObjectMapper`. :py:class:`~form.build.map.ObjectMapper` extensions are registerd with the decorator :py:func:`~pynwb.register_map`.
+
+.. code-block:: python
+
+    from pynwb import register_map
+    from form import ObjectMapper
+    @register_map(MyExtensionContainer)
+    class MyExtensionMapper(ObjectMapper)
+        ...
+
+:py:func:`~pynwb.register_map` can also be used as a function.
+
+.. code-block:: python
+
+    from pynwb import register_map
+    from form import ObjectMapper
+    class MyExtensionMapper(ObjectMapper)
+        ...
+    register_map(MyExtensionContainer, MyExtensionMapper)
+
+Write an NWBFile
+-----------------------------------------------------
+
+.. code-block:: python
+
+    from pynwb import NWBFile
+    from form import HDF5IO
+    nwbfile = NWBFile(...)
+    io = HDF5IO(...)
+    io.write(nwbfile)
+

docs/source/pynwb.rst

@@ -25,6 +25,7 @@ Submodules
    pynwb.ogen
    pynwb.ophys
    pynwb.retinotopy
+   pynwb.spec
 
 Module contents
 ---------------

docs/source/pynwb.spec.rst

@@ -0,0 +1,7 @@
+pynwb.spec module
+=================
+
+.. automodule:: pynwb.spec
+    :members:
+    :undoc-members:
+    :show-inheritance:

src/form/utils.py

@@ -245,6 +245,7 @@ def func_call(*args, **kwargs):
         #TODO: make sure this is okay --
         setattr(func_call, '__name__', func.__name__)
         setattr(func_call, docval_attr_name, _docval)
+        setattr(func_call, '__module__', func.__module__)
         return func_call
     return dec