doc updates (add install section)

doc/api.rst

@@ -14,40 +14,29 @@ Dataset.simlab (xarray accessor)
 
 Note: ``SimLabAccessor`` is a class that is decorated using
 :py:func:`xarray.register_dataset_accessor`. This allows extending
-:py:class:`xarray.Dataset` with all the methods and attributes listed below, that can be
-accessed from the ``Dataset.simlab`` property.
-Proper use of this accessor should look like:
+:py:class:`xarray.Dataset` with all the methods and properties listed below,
+which can then be accessed via the ``Dataset.simlab`` property.
+Proper use of this accessor should be like:
 
 .. code-block:: python
 
    >>> import xarray as xr   # first import xarray
-   >>> import xrsimlab       # then import xrsimlab
+   >>> import xrsimlab       # import xrsimlab (simlab accessor is registered)
    >>> ds = xr.Dataset()
    >>> ds.simlab.<meth_or_prop>   # access to the methods and properties listed below
 
-
-Methods
--------
-
 .. autosummary::
    :toctree: _api_generated/
 
+   SimLabAccessor.model
    SimLabAccessor.use_model
+   SimLabAccessor.dim_master_clock
    SimLabAccessor.set_master_clock
    SimLabAccessor.set_snapshot_clock
    SimLabAccessor.set_input_vars
    SimLabAccessor.set_snapshot_vars
-   SimLabAccessor.run
-
-Properties
-----------
-
-.. autosummary::
-   :toctree: _api_generated/
-
-   SimLabAccessor.model
-   SimLabAccessor.dim_master_clock
    SimLabAccessor.snapshot_vars
+   SimLabAccessor.run
 
 Model
 =====
@@ -75,7 +64,7 @@ Model introspection
 -------------------
 
 ``Model`` implements an immutable mapping interface where keys are
-process names and values are objects of ``Process`` subclasses. (attribute-style
+process names and values are objects of ``Process`` subclasses (attribute-style
 access is also supported).
 
 .. autosummary::
@@ -123,7 +112,7 @@ Process interface and introspection
 -----------------------------------
 
 ``Process`` implements an immutable mapping interface where keys are
-variable names and values are Variable-like objects. (attribute-style
+variable names and values are Variable objects (attribute-style
 access is also supported).
 
 .. autosummary::

doc/index.rst

@@ -3,19 +3,42 @@ xarray-simlab: xarray extension for computer model simulations
 
 **xarray-simlab** is a Python library that provides both a framework for
 creating computational models from re-usable components and a `xarray`_
-extension for setting and running simulations using the ``xarray.Dataset``
-structure.
+extension for setting and running simulations using the
+:py:class:`xarray.Dataset` structure.
 
 .. _xarray: http://xarray.pydata.org
 
-Documentation
--------------
+Documentation Index
+-------------------
+
+**Getting Started**
+
+* :doc:`installing`
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   :hidden:
+   :caption: Getting Started
+
+   installing
+
+**Help & reference**
+
+* :doc:`api`
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Help & reference
 
    api
 
+Get in touch
+------------
+
+- Report bugs, suggest features or view the source code `on GitHub`_.
+
+.. _on GitHub: http://github.com/benbovy/xarray-simlab
 
 License
 -------

doc/installing.rst

@@ -0,0 +1,59 @@
+.. _installing:
+
+Install xarray-simlab
+=====================
+
+Required dependencies
+---------------------
+
+- Python 3.4 or later.
+- `numpy <http://www.numpy.org/>`__
+- `xarray <http://xarray.pydata.org>`__ (0.8.0 or later)
+
+Optional dependencies
+---------------------
+
+For model visualization
+~~~~~~~~~~~~~~~~~~~~~~~
+
+- `graphviz <http://graphviz.readthedocs.io>`__
+
+Install from source
+-------------------
+
+There is currently no ``xarray-simlab`` release available at PyPi_
+or conda-forge_.
+
+Be sure you have the required dependencies (numpy and xarray)
+installed first. You might consider using conda_ to install them::
+
+    $ conda install xarray numpy pip -c conda-forge
+
+A good practice (especially for development purpose) is to install the packages
+in a separate environment, e.g. using conda::
+
+    $ conda create -n simlab_py36 python=3.6 xarray numpy pip -c conda-forge
+    $ source activate simlab_py36
+
+Then you can clone the ``xarray-simlab`` git repository and install it
+using ``pip`` locally::
+
+    $ git clone https://github.com/benbovy/xarray-simlab
+    $ cd xarray-simlab
+    $ pip install .
+
+For development purpose, use the following command::
+
+    $ pip install -e .
+
+.. _PyPi: https://pypi.python.org/pypi
+.. _conda-forge: https://conda-forge.github.io/
+.. _conda: http://conda.io/
+
+Import xarray-simlab
+--------------------
+
+To make sure that ``xarray-simlab`` is correctly installed, try import it in a
+Python console::
+
+    >>> import xrsimlab

xrsimlab/xr_accessor.py

@@ -116,8 +116,8 @@ def set_master_clock(self, dim, data=None, start=0., end=None,
         Raises
         ------
         ValueError
-            - If Dataset has already a dimension named `dim`.
-            - In case of ambiguous combination of `nsteps`, `step` and `end`.
+            If Dataset has already a dimension named `dim`
+            or in case of ambiguous combination of `nsteps`, `step` and `end`.
 
         """
         if dim in self._obj.dims: