Improve job.data, project.data (H5Store) examples. (#235)

* Point to H5Store for job.data, project.data examples.

* Edit doc string for job.data

* Update project docstring

* Not sure how to link to signac-doc repo

* Not sure how to link topic guides 

In different repository?

* Consistency with docstring job

* project docstring consistency

* Add Project.stores to documentation rubric.

* Add proper link to job.data.

* Add proper link, fix formatting and typo.

* Minor formatting updates.

doc/api.rst

@@ -61,6 +61,7 @@ The Project
     Project.repair
     Project.reset_statepoint
     Project.root_directory
+    Project.stores
     Project.sync
     Project.update_cache
     Project.update_statepoint

signac/contrib/job.py

@@ -293,7 +293,7 @@ def stores(self):
             H5Store(job.fn('my_data.h5'))['array'] = np.random((32, 4))
 
         Both the `job.stores` and the `H5Store` itself support attribute
-        access. The above example could therefore also be expressed as
+        access. The above example could therefore also be expressed as:
 
         .. code-block:: python
 
@@ -308,7 +308,11 @@ def stores(self):
 
     @property
     def data(self):
-        """The data store associated with this job.
+        """The data associated with this job.
+
+        This property should be used for large array-like data, which can't be
+        stored efficiently in the job document. For examples and usage, see
+        `Job Data Storage <https://docs.signac.io/en/latest/jobs.html#job-data-storage>`_.
 
         Equivalent to:
 

signac/contrib/project.py

@@ -346,17 +346,23 @@ def stores(self):
         Use this property to access an HDF5 file within the project's root
         directory using the H5Store dict-like interface.
 
-        This is an example for accessing an HDF5 file called 'my_data.h5' within
-        the project's root directory:
+        This is an example for accessing an HDF5 file called ``'my_data.h5'``
+        within the project's root directory:
+
+        .. code-block:: python
 
             project.stores['my_data']['array'] = np.random((32, 4))
 
         This is equivalent to:
 
+        .. code-block:: python
+
             H5Store(project.fn('my_data.h5'))['array'] = np.random((32, 4))
 
         Both the `project.stores` and the `H5Store` itself support attribute
-        access. The above example could therefore also be expressed as
+        access. The above example could therefore also be expressed as:
+
+        .. code-block:: python
 
             project.stores.my_data.array = np.random((32, 4))
 
@@ -369,9 +375,18 @@ def stores(self):
     def data(self):
         """The data associated with this project.
 
+        This property should be used for large array-like data, which can't be
+        stored efficiently in the project document. For examples and usage, see
+        `Centralized Project Data
+        <https://docs.signac.io/en/latest/projects.html#centralized-project-data>`_.
+
+        See :class:`~..core.h5store.H5Store` for usage examples.
+
         Equivalent to:
 
-            return project.store['signac_data']
+        .. code-block:: python
+
+            return project.stores['signac_data']
 
         :return: An HDF5-backed datastore.
         :rtype: :class:`~..core.h5store.H5Store`

signac/core/h5store.py

@@ -262,10 +262,10 @@ class H5Store(MutableMapping):
             assert h5s.foo == 'bar'
             assert h5s['foo'] == 'bar'
 
-    The H5Store can be used as a context manager to ensure that the underlying file
-    is opened, however most built-in types can be read and stored without the need
-    to _explicitly_ open the file. However, to access arrays (reading or writing),
-    the file must always be opened!
+    The H5Store can be used as a context manager to ensure that the underlying
+    file is opened, however most built-in types (excluding arrays) can be read
+    and stored without the need to _explicitly_ open the file. **To
+    access arrays (reading or writing), the file must always be opened!**
 
     To open a file in read-only mode, use the :py:meth:`.open` method with ``mode=r``: