DOC: Update tutorial

doc/source/index.rst

@@ -30,7 +30,7 @@ What Next
 ---------
 
 - :doc:`Installation </installation>`
-- :doc:`Tutorial <tutorial>`
+- :doc:`Tutorial <tutorial/index>`
 - :doc:`Reference </reference/index>`
 
 .. toctree::
@@ -40,7 +40,7 @@ What Next
    whatsnew
    installation
    spyder
-   tutorial
+   tutorial/index
    userguide/index
    reference/index
 

doc/source/installation.rst

@@ -3,11 +3,21 @@ Installation
 
 .. note::
 
-   For `lifelib`_ users, when installing `lifelib`_ using
-   ``pip``, modelx is automatically installed due to its dependency, so
-   no need to install modelx separately.
+    This page explains how to install and configure
+    modelx and related packages manually, and is intended for
+    advanced Python users or Linux/Mac users.
+
+    For Windows users,
+    it is recommended to use the latest custom WinPython with modelx,
+    which is available `here <https://lifelib.io/download.html>`_.
+    You can start using modelx just by unzipping the downloaded file,
+    and no need to follow the steps on this page.
+
+
+.. contents:: Contents
+   :depth: 1
+   :local:
 
-.. _lifelib: http://lifelib.io
 
 Python version
 --------------
@@ -51,8 +61,9 @@ to enable modelx to interface with Excel files.
 
 Spyder
 ^^^^^^
-If you use modelx with `Spyder <https://www.spyder-ide.org/>`_,
-a plugin for modelx is available.
+To use modelx with `Spyder <https://www.spyder-ide.org/>`_,
+a popular open-source Python IDE,
+A plugin for modelx is available.
 ``spyder-modelx`` is a separate package to add custom IPython consoles
 and Modelx explorer, a widget that shows the current model in a tree view.
 The supported Spyder version is 3.2.5 or newer.
@@ -63,11 +74,12 @@ Installing modelx
 
 .. note::
 
-   If you install :ref:`Spyder plugin for modelx <install-spyder-plugin>`
-   as explained below,
-   no need to install modelx separately as modelx is installed
-   together with the plugin, so skip to the
-   :ref:`Plugin installation <install-spyder-plugin>` section.
+   For `lifelib`_ users, when installing `lifelib`_ using
+   ``pip``, modelx is automatically installed due to its dependency, so
+   no need to install modelx separately.
+
+.. _lifelib: http://lifelib.io
+
 
 Just like other Python packages, you can install ``modelx`` by
 running ``pip`` command from a terminal on Linux, or from a command prompt on
@@ -104,3 +116,80 @@ Spyder integration
 `Spyder`_ is a popular open-source Python IDE, and
 a Spyder plugin for modelx is avaialble. To install and use the plugin,
 see the :doc:`spyder` page
+
+
+Configuring Spyder
+^^^^^^^^^^^^^^^^^^
+
+**Disable User Module Reloader**
+
+When you use modelx with Spyder, sometimes you may want to re-run the
+same file in the editor window multiple times in the same IPython session.
+You don't want to reload modelx because reloading modelx module creates
+multiple instances of modelx systems within the same Python process,
+causing models created before and after a reload to reside in different
+modelx systems. To avoid that, you need to change *User Module Rloader (UMR)*
+setting.
+
+From the Spyder menu, select *Tools->Preferences* to bring up Preferences window.
+Choose *Python interpreter* in the left pane, and you'll find an area titled
+*User Module Reloader (UMR)* on the bottom right side of the Preferences window.
+Leave *Enable UMR* option checked,
+click *Set UMR excluded(not reloaded) modules* and then UMR dialog box pops up
+as the figure blow.
+Enter "modelx" in the dialog box. This prevents
+Spyder from reloading the modelx module every time you re-run the same script
+from *Run* menu, while allowing other modules to be reloaded.
+
+Note that you need to restart Spyder to bring the change into effect.
+
+.. figure:: /images/spyder/PreferencesUMR.png
+
+   User Module Reloader setting
+
+
+**Import modelx at IPython startup**
+
+When you use modelx in IPython, you need to import modelx first.
+Doing so every time you open a new IPython session is tedious,
+so there's a way to import modelx at each IPython session's startup.
+From the Spyder menu, select *Tools->Preferences* to bring up Preferences window.
+Choose *IPython console* in the left pane, and select
+*Startup* tab from the tabs on the right.
+Enter ``import modelx as mx`` in the box titled *Lines:* in the *Run code* area,
+and click *Okay*. Next time you open a new IPython session,
+modelx is imported as ``mx`` in the IPython's global namespace.
+
+.. figure:: /images/spyder/PreferencesStartup.png
+
+   IPython startup setting
+
+
+Installing Spyder plugin for modelx
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The plugin is available as a separate Python package named ``spyder-modelx``.
+
+The supported version of Spyder is 3.2.5 or newer. The plugin does not
+work with Spyder versions older than 3.2.5.
+
+``spyder-modelx`` package is available on PyPI, and
+can be installed using ``pip`` command.
+
+If you're using Anaconda distribution,
+run the following command in Anaconda command prompt to install the plugin
+after installing ``modelx``::
+
+    $ pip install --no-deps spyder-modelx
+
+.. warning::
+
+    On Anaconda environments, install modelx manually if it is not yet installed.
+    Do not forget to add ``--no-deps`` parameter when installing
+    spyder-modelx on Anaconda environments, otherwise,
+    `pip` will overwrite packages spyder-modelx depends on.
+
+If Spyder is running while the plugin gets installed, close Spyder once
+and restart it to bring the plugin into effect.
+
+.. _MxExplorerAndMxConsole:

doc/source/spyder.rst

@@ -46,82 +46,6 @@ to rearrange the widgets positions in the main window as you like.
 .. _Spyder: https://www.spyder-ide.org/
 .. _install-spyder-plugin:
 
-Configure Spyder
-----------------
-
-**Disable User Module Reloader**
-
-When you use modelx with Spyder, sometimes you may want to re-run the
-same file in the editor window multiple times in the same IPython session.
-You don't want to reload modelx because reloading modelx module creates
-multiple instances of modelx systems within the same Python process,
-causing models created before and after a reload to reside in different
-modelx systems. To avoid that, you need to change *User Module Rloader (UMR)*
-setting.
-
-From the Spyder menu, select *Tools->Preferences* to bring up Preferences window.
-Choose *Python interpreter* in the left pane, and you'll find an area titled
-*User Module Reloader (UMR)* on the bottom right side of the Preferences window.
-Leave *Enable UMR* option checked,
-click *Set UMR excluded(not reloaded) modules* and then UMR dialog box pops up
-as the figure blow.
-Enter "modelx" in the dialog box. This prevents
-Spyder from reloading the modelx module every time you re-run the same script
-from *Run* menu, while allowing other modules to be reloaded.
-
-Note that you need to restart Spyder to bring the change into effect.
-
-.. figure:: /images/spyder/PreferencesUMR.png
-
-   User Module Reloader setting
-
-
-**Import modelx as IPython startup**
-
-When you use modelx in IPython, you need to import modelx first.
-Doing so every time you open a new IPython session is tedious,
-so there's a way to import modelx at each IPython session's startup.
-From the Spyder menu, select *Tools->Preferences* to bring up Preferences window.
-Choose *IPython console* in the left pane, and select
-*Startup* tab from the tabs on the right.
-Enter ``import modelx as mx`` in the box titled *Lines:* in the *Run code* area,
-and click *Okay*. Next time you open a new IPython session,
-modelx is imported as ``mx`` in the IPython's global namespace.
-
-.. figure:: /images/spyder/PreferencesStartup.png
-
-   IPython startup setting
-
-
-
-Installing Spyder plugin for modelx
------------------------------------
-
-The plugin is available as a separate Python package named ``spyder-modelx``.
-
-The supported version of Spyder is 3.2.5 or newer. The plugin does not
-work with Spyder versions older than 3.2.5.
-
-``spyder-modelx`` package is available on PyPI, and
-can be installed using ``pip`` command.
-
-If you're using Anaconda distribution,
-run the following command in Anaconda command prompt to install the plugin
-after installing ``modelx``::
-
-    $ pip install --no-deps spyder-modelx
-
-.. warning::
-
-    On Anaconda environments, install modelx manually if it is not yet installed.
-    Do not forget to add ``--no-deps`` parameter when installing
-    spyder-modelx on Anaconda environments, otherwise,
-    `pip` will overwrite packages spyder-modelx depends on.
-
-If Spyder is running while the plugin gets installed, close Spyder once
-and restart it to bring the plugin into effect.
-
-.. _MxExplorerAndMxConsole:
 
 MxExplorer and MxConsole
 ------------------------

doc/source/tutorial.rst → doc/source/tutorial/api_tutorial.rst

@@ -1,15 +1,20 @@
-Tutorial
-========
-This tutorial aims to introduce core concepts and features of modelx, and
-demonstrate how to use modelx by going through some examples.
+modelx API Tutorial
+===================
+
+This modelx API tutorial an introduction for using modelx API functions
+and objects directly in Python scripts, or from IPython interactive sessions.
 
 This tutorial supplements modelx reference,
 which is build from docstrings of the API functions and classes.
 The reference should cover the details of each API element,
 which may not be fully explained in this tutorial.
 
-Typical workflow
-----------------
+.. contents:: Contents
+   :local:
+
+modelx API
+----------
+
 modelx is a Python package, and you use it by writing a Python script
 and importing it, as you would normally do with any other Python package.
 
@@ -30,40 +35,6 @@ in a Python shell window where you are prompted to enter Python code to
 evaluate the model. Jupyter Notebook and many other popular Python shell
 environments have similar capability.
 
-Model, Space and Cells
-----------------------
-Before taking a look at the very first example, you might want to
-have an idea on what Model, Space and Cells are, as those three types
-of objects are central to modelx.
-
-Model, Space and Cells are to modelx
-what workbook, worksheet and cells are to a spreadsheet program respectively,
-although there are differences.
-The diagram below illustrates containment
-relationships between those objects.
-
-.. figure:: images/ObjectContainment.png
-
-   Model, Space and Cells
-
-
-A model is a workspace that contains all the modelx objects.
-It can be saved to a file and loaded again.
-A model contains spaces. In turn, spaces can contain cells and also other
-spaces (subspaces). Each cells ('cells' is singular here)
-belongs to one and only one space.
-We call the object that contains another object, the parent of the contained
-object.
-The parent of a cells is the space that contains the cells,
-and the parent of a space is the model or space that contains the space.
-Spaces also serves as the namespace for contained
-cells but we'll get to this later.
-
-A Cells can have a formula that calculates the cells' values, just like
-spreadsheet cells can have formulas. Cells values are either calculated
-by the formula or assigned as an input. We will learn how to define
-cells formulas through the examples soon.
-
 
 Basic Operation
 ---------------
@@ -72,7 +43,7 @@ such as creating models, spaces and cells,
 by talking a closer look at the simple example
 we saw in the overview section.
 
-.. literalinclude:: samples/example_overview.py
+.. literalinclude:: /samples/example_overview.py
    :lines: 1-11
 
 Importing modelx
@@ -81,7 +52,7 @@ Importing modelx
 To start using modelx, import the package by the import statement, as is the
 case with any other package.
 
-.. literalinclude:: samples/example_overview.py
+.. literalinclude:: /samples/example_overview.py
    :lines: 1
 
 By doing so, you get to use modelx API functions in ``__main__`` module.
@@ -187,7 +158,7 @@ There are a few ways to create a cells object and defiene the formula
 associated with the cells. As seen in the example above,
 one way is to define a python function with ``defcells`` decorator.
 
-.. literalinclude:: samples/example_overview.py
+.. literalinclude:: /samples/example_overview.py
    :lines: 3-
 
 By ``defcells`` decorator, the name ``fibo`` in this scope points
@@ -590,7 +561,7 @@ to get output shorter. As long as we use a constant mortality age,
 it shouldn't affect the results whether the starting age is 0 or 50.
 Below the modelx code for this life model:
 
-.. literalinclude:: samples/sample_inheritance.py
+.. literalinclude:: /samples/sample_inheritance.py
    :lines: 6-21
 
 The second to last line of the code above has the same effect as putting
@@ -652,7 +623,7 @@ discounting rate for the present value calculation.
 Continued from the previous code, we are going to derive the ``TermLife`` space
 from the ``Life`` space, to add the benefits and present value calculations.
 
-.. literalinclude:: samples/sample_inheritance.py
+.. literalinclude:: /samples/sample_inheritance.py
    :lines: 25-41
 
 The first line in the sample above creates ``TermLife`` space derived
@@ -667,7 +638,7 @@ that are not defined yet. Those are ``n``, ``disc_rate``.
 We need to define those in the ``TermLife`` space.
 The reference ``x0`` is inherited from the ``Life`` space.
 
-.. literalinclude:: samples/sample_inheritance.py
+.. literalinclude:: /samples/sample_inheritance.py
    :lines: 46-47
 
 
@@ -714,7 +685,7 @@ below shows the relationships of the 3 spaces considered here.
 A space from which an arrow originates is derived from the space the
 arrow points to.
 
-.. figure:: images/Inheritance1.png
+.. figure:: /images/Inheritance1.png
    :align: center
 
    Life, TermLife and Endowment
@@ -729,7 +700,7 @@ and maturity benefits, but here we are considering an probabilistic model,
 so the benefits would be the sum of expected value of death and maturity
 benefits:
 
-.. literalinclude:: samples/sample_inheritance.py
+.. literalinclude:: /samples/sample_inheritance.py
    :lines: 53-62
 
 And the same operations on the ``Endowment`` space produces the following
@@ -814,11 +785,11 @@ it is also the base space of them.
 This inheritance is represented by the unfilled arrowhead next the
 filled diamond.
 
-.. figure:: images/Inheritance2.png
+.. figure:: /images/Inheritance2.png
 
 Below is a script to extend the model as we designed above.
 
-.. literalinclude:: samples/sample_inheritance.py
+.. literalinclude:: /samples/sample_inheritance.py
    :lines: 72-86
 
 The ``params`` function is passed to the constructor of the ``Policy`` space