working on documentation, adding coverage

.travis.yml

@@ -3,5 +3,13 @@ python:
   - "2.7"
   - "3.6"
 
-install: "pip install -r requirements.txt"
-script: pytest
+install:
+    - pip install -r requirements.txt
+    - pip install pytest-cov
+    - pip install codecov
+
+script:
+    - py.test --cov=grmpy
+
+after_success:
+    - codecov

docs/bibliography.rst

@@ -0,0 +1,2 @@
+Bibliography
+============

docs/changes.rst

@@ -0,0 +1,9 @@
+Changes
+=======
+
+This is a record of all past ``grmpy`` releases and what went into them in reverse chronological order. We follow `semantic versioning <http://semver.org/>`_ and all releases are available on `PyPI <https://pypi.python.org/pypi/respy>`_.
+
+1.0.0 - 2018-XX-XX
+------------------
+
+This is the initial release of the ``grmpy`` package.

docs/conf.py

@@ -31,7 +31,16 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+    'sphinxcontrib.bibtex',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -83,7 +92,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -171,5 +180,3 @@
 
 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ['search.html']
-
-

docs/credits.rst

@@ -0,0 +1,22 @@
+Contact and Credits
+===================
+
+If you have any questions or comments, please do not hesitate to contact us directly.
+
+.. image:: https://badges.gitter.im/Join%20Chat.svg
+   :target: https://gitter.im/grmToolbox/contact?utm_source=share-link&utm_medium=link&utm_campaign=share-link
+
+Development Lead
+^^^^^^^^^^^^^^^^
+
+`Philipp Eisenhauer <https://github.com/peisenha>`_
+
+Contributors
+^^^^^^^^^^^^
+
+`Sebastian Becker <https://github.com/sebecker>`_
+
+Acknowledgments
+^^^^^^^^^^^^^^^
+
+We appreciate the financial support of the `AXA Research Fund <https://www.axa-research.org/>`_ and the  `University of Bonn <https://www.uni-bonn.de>`_. We are indebted to the open source community as we build on top of numerous open source tools such as the `SciPy Stack <https://www.scipy.org>`_ and `statsmodels <http://statsmodels.sourceforge.net/>`.

docs/index.rst

@@ -6,15 +6,27 @@
 Welcome to grmpy's documentation!
 =================================
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+`PyPI <https://pypi.python.org/pypi/grmpy>`_ | `GitHub <https://github.com/grmToolbox/grmpy>`_  | `Issues <https://github.com/grmToolbox/grmpy/issues>`_
+
+``grmpy`` is an open-source Python package for the simulation and estimation of generalized Roy Model (Heckman & Vytlacil, 2005). It's main purpose is to serve as a teaching tool to promote the conceptual framework provided by the generalized Roy model which allows to illustrate a variety of issues in the econometrics of policy evaluation.
+
+We build on the following main references:
 
+    Heckman, J. J., and Vytlacil, E. J. (2007a). [Econometric evaluation of social programs, Part I: Causal effects, structural models and econometric policy evaluation.](http://ac.els-cdn.com/S1573441207060709/1-s2.0-S1573441207060709-main.pdf?_tid=b933f5c8-6bbe-11e7-8ae8-00000aacb35d&acdnat=1500385435_c69182d36b79b66bbce5f5a7c593617c) In Heckman, J. J., and Leamer, E. E., editors, *Handbook of Econometrics*, volume 6B, pages 4779–4874. Elsevier Science, Amsterdam, Netherlands.
 
+    Heckman, J. J., and Vytlacil, E. J. (2007b). [Econometric evaluation of social programs, Part II: Using the marginal treatment effect to organize alternative economic estimators to evaluate social programs and to forecast their effects in new environments.](http://ac.els-cdn.com/S1573441207060710/1-s2.0-S1573441207060710-main.pdf?_tid=5ccb4ace-6bbf-11e7-807b-00000aab0f26&acdnat=1500385710_c3706f18138fabe356b0f3ebddd75670) In Heckman, J. J. and Leamer, E. E., editors, *Handbook of Econometrics*, volume 6B, pages 4875–5144. Elsevier Science, Amsterdam, Netherlands.
 
-Indices and tables
-==================
+.. image:: https://img.shields.io/github/license/mashape/apistatus.svg?maxAge=2592000   :target:
+
+**Contents:**
+
+.. toctree::
+    :maxdepth: 1
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+    installation
+    tutorial
+    reliability
+    software_engineering
+    credits
+    changes
+    bibliography

docs/installation.rst

@@ -0,0 +1,37 @@
+Installation
+============
+
+The ``grmpy`` package can be conveniently installed from the `Python Package Index <https://pypi.python.org/pypi>`_ (PyPI) or directly from its source files. We currently support Python 2.7 and Python 3.6 on Linux systems.
+
+Python Package Index
+--------------------
+
+You can install the stable version of the package the usual way.
+
+.. code-block:: bash
+
+   $ pip install grmpy
+
+Source Files
+------------
+
+You can download the sources directly from our `GitHub repository <https://github.com/grmToolbox/grmpy>`_.
+
+.. code-block:: bash
+
+   $ git clone https://github.com/grmpy/package.git
+
+Once you obtained a copy of the source files, installing the package in editable model is straightforward.
+
+.. code-block:: bash
+
+   $ pip install -e .
+
+Test Suite
+----------
+
+Please make sure that the package is working properly by running our test suite using ``pytest``.
+
+.. code-block:: bash
+
+  $ python -c "import grmpy; grmpy.test()"

docs/reliability.rst

@@ -0,0 +1,4 @@
+Reliability
+===========
+
+We document the results of two straightforward Monte Carlo exercises to illustrate the reliability of the ``grmpy`` package. 

docs/requirements.txt

@@ -0,0 +1 @@
+sphinxcontrib-bibtex

docs/software_engineering.rst

@@ -0,0 +1,57 @@
+Software Engineering
+====================
+
+We now briefly discuss our software engineering practices that help us to ensure the transparency, reliability, scalability, and extensibility of the ``grmpy`` package.
+
+Test Battery
+------------
+
+.. image:: https://codecov.io/gh/grmpy/package/branch/master/graph/badge.svg
+   :target: https://codecov.io/gh/grmpy/package
+
+We use `pytest <http://docs.pytest.org>`_ as our test runner. We broadly group our tests in four categories:
+
+* **property-based testing**
+
+    We create random model parameterizations and estimation requests and test for a valid return of the program.
+
+* **reliability testing**
+
+    We conduct numerous Monte Carlo exercises to ensure that we can recover the true underlying parameterization with an estimation. Also by varying the tuning parameters of the estimation (e.g. random draws for integration) and the optimizers, we learn about their effect on estimation performance.
+
+
+Documentation
+-------------
+
+.. image:: https://readthedocs.org/projects/grmpy/badge/?version=latest
+   :target: http://respy.readthedocs.io/en/latest/?badge=latest
+   :alt: Documentation Status
+
+The documentation is created using `Sphinx <http://www.sphinx-doc.org/>`_ and hosted on `Read the Docs <https://readthedocs.org/>`_.
+
+Code Review
+-----------
+
+.. image:: https://api.codacy.com/project/badge/Grade/3dd368fb739c49d78d910676c9264a81
+   :target: https://www.codacy.com/app/eisenhauer/respy?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=restudToolbox/package&amp;utm_campaign=Badge_Grade
+
+.. image:: https://landscape.io/github/restudToolbox/package/master/landscape.svg?style=flat
+    :target: https://landscape.io/github/restudToolbox/package/master
+    :alt: Code Health
+
+We use several automatic code review tools to help us improve the readability and maintainability of our code base. For example, we work with `Codacy <https://www.codacy.com/app/eisenhauer/respy/dashboard>`_ and `Landscape <https://landscape.io/github/restudToolbox/package>`_
+
+Continuous Integration Workflow
+-------------------------------
+
+.. image:: https://travis-ci.org/restudToolbox/package.svg?branch=master
+   :target: https://travis-ci.org/restudToolbox/package
+
+.. image:: https://requires.io/github/restudToolbox/package/requirements.svg?branch=master
+    :target: https://requires.io/github/restudToolbox/package/requirements/?branch=master
+    :alt: Requirements Status
+
+.. image:: https://badge.fury.io/py/respy.svg
+    :target: https://badge.fury.io/py/respy
+
+We set up a continuous integration workflow around our `GitHub Organization <https://github.com/restudToolbox>`_. We use the continuous integration services provided by `Travis CI <https://travis-ci.org/restudToolbox/package>`_. `tox <https://tox.readthedocs.io>`_ helps us to ensure the proper workings of the package for alternative Python implementations. Our build process is managed by `Waf <https://waf.io/>`_. We rely on `Git <https://git-scm.com/>`_ as our version control system and follow the `Gitflow Workflow <https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow>`_. We use `GitLab <https://gitlab.com/restudToolbox/package/issues>`_ for our issue tracking. The package is distributed through `PyPI <https://pypi.python.org/pypi/respy>`_ which automatically updated from our development server.

docs/tutorial.rst

@@ -0,0 +1,9 @@
+Tutorial
+========
+
+We now illustrate the basic capabilities of the ``grmpy`` package. We start with the model specification and then turn to some example use cases.
+
+Model Specification
+-------------------
+
+The model is specified in an initialization file.