Merge pull request #121 from tomalrussell/feature/parameters

Reduce smif.parameters API, introducing a Parameter object. 

Use `better-apidoc` to template module reference documentation and avoid duplicated documentation of `__all__` imports in subpackages.

.environment.yml

@@ -69,12 +69,20 @@ dependencies:
 - scikit-learn=0.19.0=np113py35_0
 - scipy=0.19.1=np113py35_0
 - pip:
+  - alabaster==0.7.10
   - aspy.yaml==1.0.0
+  - babel==2.5.3
   - backports.functools-lru-cache==1.4
+  - better-apidoc==0.1.2
   - cached-property==1.3.1
+  - chardet==3.0.4
+  - colorama==0.3.9
   - decorator==4.1.2
+  - docutils==0.14
   - flask==0.12.2
   - identify==1.0.7
+  - idna==2.6
+  - imagesize==0.7.1
   - isodate==0.6.0
   - itsdangerous==0.24
   - jinja2==2.10
@@ -83,5 +91,11 @@ dependencies:
   - nodeenv==1.2.0
   - pint==0.8.1
   - pre-commit==1.4.1
+  - pygments==2.2.0
+  - requests==2.18.4
+  - snowballstemmer==1.2.1
+  - sphinx==1.6.6
+  - sphinxcontrib-websupport==1.0.1
+  - urllib3==1.22
   - virtualenv==15.1.0
   - werkzeug==0.12.2

docs/_templates/README.txt

@@ -0,0 +1,7 @@
+# Templates
+
+These templates are used by better-apidoc to produce customised apidoc output
+in the ../api directory for sphinx to use to build documentation from Python
+docstrings.
+
+For reference, see https://github.com/goerz/better-apidoc#templating

docs/_templates/module.rst

@@ -0,0 +1,71 @@
+{{ fullname }} module
+{% for item in range(fullname|length) -%}={%- endfor %}
+
+.. currentmodule:: {{ fullname }}
+
+.. automodule:: {{ fullname }}
+    {% if members -%}
+    :members: {{ members|join(", ") }}
+    :undoc-members:
+    :show-inheritance:
+    :member-order: bysource
+    {%- endif %}
+
+
+    Summary
+    -------
+
+    {%- if exceptions %}
+
+    Exceptions:
+
+    .. autosummary::
+        :nosignatures:
+{% for item in exceptions %}
+        {{ item }}
+{%- endfor %}
+    {%- endif %}
+
+    {%- if classes %}
+
+    Classes:
+
+    .. autosummary::
+        :nosignatures:
+{% for item in classes %}
+        {{ item }}
+{%- endfor %}
+    {%- endif %}
+
+    {%- if functions %}
+
+    Functions:
+
+    .. autosummary::
+        :nosignatures:
+{% for item in functions %}
+        {{ item }}
+{%- endfor %}
+    {%- endif %}
+
+    {%- if data %}
+
+    Data:
+
+    .. autosummary::
+        :nosignatures:
+{% for item in data %}
+        {{ item }}
+{%- endfor %}
+    {%- endif %}
+
+{% if all_refs %}
+    ``__all__``: {{ all_refs|join(", ") }}
+{%- endif %}
+
+
+{% if members %}
+    Reference
+    ---------
+
+{%- endif %}

docs/_templates/package.rst

@@ -0,0 +1,90 @@
+{{ fullname }} package
+{% for item in range(fullname|length) -%}={%- endfor %}
+
+.. automodule:: {{ fullname }}
+    {% if members -%}
+    :members: {{ members|join(", ") }}
+    :undoc-members:
+    :show-inheritance:
+    {%- endif %}
+
+
+{% if submodules %}
+    Submodules:
+
+    .. toctree::
+       :maxdepth: 1
+{% for item in submodules %}
+       {{ fullname }}.{{ item }}
+       {%- endfor %}
+    {%- endif -%}
+
+{% if subpackages %}
+    Subpackages:
+
+    .. toctree::
+       :maxdepth: 1
+{% for item in subpackages %}
+       {{ fullname }}.{{ item }}
+       {%- endfor %}
+    {%- endif %}
+
+{% if members %}
+    {%- if exceptions %}
+
+    Exceptions:
+
+    .. autosummary::
+        :nosignatures:
+{% for item in exceptions %}
+        {{ item }}
+{%- endfor %}
+    {%- endif %}
+
+    {%- if classes %}
+
+    Classes:
+
+    .. autosummary::
+        :nosignatures:
+{% for item in classes %}
+        {{ item }}
+{%- endfor %}
+    {%- endif %}
+
+    {%- if functions %}
+
+    Functions:
+
+    .. autosummary::
+        :nosignatures:
+{% for item in functions %}
+        {{ item }}
+{%- endfor %}
+    {%- endif %}
+{%- endif %}
+
+    {%- if data %}
+
+    Data:
+
+    .. autosummary::
+        :nosignatures:
+{% for item in data %}
+        {{ item }}
+{%- endfor %}
+    {%- endif %}
+
+{% if all_refs %}
+    Exports
+    -------
+
+    ``__all__``: {{ all_refs|join(", ") }}
+{%- endif %}
+
+
+{% if members %}
+    Reference
+    ---------
+
+{%- endif %}

docs/conf.py

@@ -24,7 +24,8 @@
 import os
 import sys
 
-from sphinx import apidoc
+# from sphinx import apidoc
+import better_apidoc
 
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -36,9 +37,18 @@
 
 output_dir = os.path.join(__location__, "../docs/api")
 module_dir = os.path.join(__location__, "../smif")
-cmd_line_template = "sphinx-apidoc -f -M -o {outputdir} {moduledir}"
-cmd_line = cmd_line_template.format(outputdir=output_dir, moduledir=module_dir)
-apidoc.main(cmd_line.split(" "))
+templates_dir = os.path.join(__location__, "../docs/_templates")
+
+better_apidoc.main([
+    'better-apidoc',
+    '-t',
+    templates_dir,
+    '--force',
+    '--separate',
+    '-o',
+    output_dir,
+    module_dir
+])
 
 # -- General configuration -----------------------------------------------------
 

docs/index.rst

@@ -1,28 +1,58 @@
 smif
 ----
 
-**smif** (a simulation modelling integration framework) is a framework for
-handling the creation of system-of-systems models. The framework handles inputs
-and outputs, dependencies between models, persistence of data and the
-communication of state across years.
+.. image:: https://img.shields.io/badge/github-nismod%2Fsmif-brightgreen.svg
+    :target: https://github.com/nismod/smif/
+    :alt: nismod/smif on github
+
+.. image:: https://travis-ci.org/nismod/smif.svg?branch=master
+    :target: https://travis-ci.org/nismod/smif
+    :alt: Travis CI build status
+
+.. image:: https://coveralls.io/repos/github/nismod/smif/badge.svg?branch=master
+    :target: https://coveralls.io/github/nismod/smif?branch=master
+    :alt: Coveralls code coverage
+
+.. image:: https://img.shields.io/pypi/v/smif.svg
+    :target: https://pypi.python.org/pypi/smif
+    :alt: PyPI package
+
+.. image:: https://img.shields.io/conda/vn/conda-forge/smif.svg
+    :target: https://anaconda.org/conda-forge/smif
+    :alt: conda-forge package
+
+**smif** is a framework for handling the creation of system-of-systems models.
+The framework handles inputs and outputs, dependencies between models,
+persistence of data and the communication of state across years.
 
 This early version of the framework handles simulation models that simulate the
-operation of a system within a year and exposes an interface to a planning
-module which will allow different algorithms to be used against a common API.
+operation of a system within a year. **smif** will expose an interface to a
+planning module which allows different decision-making algorithms to work
+against a common API.
+
+**smif** is written in Python (>=3.5) and uses wrappers which implement a
+consistent interface in order to run models written in many languages.
+
+A word from our sponsors
+========================
+
+**smif** is being written and developed in the `Environmental Change Institute,
+in the University of Oxford <http://www.eci.ox.ac.uk>`_ funded by EPSRC as part
+of the `Infrastructure Transitions Research Consortium
+<http://www.itrc.org.uk/>`_ MISTRAL research programme.
 
 Contents
 ========
 
 .. toctree::
    :maxdepth: 2
 
-   README <readme>
    Getting Started <getting_started>
    Concept <concept>
 
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 3
 
    Reference <api/modules>
 

smif/cli/__init__.py

@@ -85,7 +85,7 @@
 from smif.convert.interval import get_register as get_interval_register
 from smif.convert.interval import IntervalSet
 from smif.http_api import create_app
-from smif.parameters.narrative import Narrative
+from smif.parameters import Narrative
 from smif.modelrun import ModelRunBuilder
 from smif.model.sos_model import SosModelBuilder
 from smif.model.sector_model import SectorModelBuilder

smif/model/__init__.py

@@ -185,9 +185,7 @@ def add_parameter(self, parameter_dict):
             Contains the keys ``name``, ``description``,  ``absolute_range``,
             ``suggested_range``, ``default_value``, ``units``
         """
-        parameter_dict['parent'] = self
-
-        self._parameters.add_parameters_from_list([parameter_dict])
+        self._parameters.add_parameter(parameter_dict)
 
     @property
     def parameters(self):

smif/modelrun.py

@@ -37,7 +37,7 @@ class ModelRun(object):
     scenarios: dict
         For each scenario set, a mapping to a valid scenario within that set
     narratives: list
-        A list of :class:`smif.parameters.narrative.Narrative` objects
+        A list of :class:`smif.parameters.Narrative` objects
     strategies: dict
     status: str
     logger: logging.Logger