Documentation refactor (#302)

* pydata sphinx theme
* refactoring docs structure

Author: jonathf

.circleci/config.yml

@@ -76,7 +76,7 @@ jobs:
           command: |
             source /home/circleci/venv/bin/activate
             coverage run --source=chaospy/ --module pytest --nbval-lax --doctest-modules \
-                chaospy/ tests/ docs/notebooks/*.ipynb docs/*.rst docs/*/*.rst README.rst
+                chaospy/ tests/ docs/*/*.ipynb docs/*/*.rst README.rst
             bash <(curl -s https://codecov.io/bash)
   deploy:
     executor: python-container

.gitignore

@@ -6,3 +6,4 @@ __pycache__
 .mypy_cache
 .envrc
 docs/.build
+docs/reference/api

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "numpoly"]
+	path = numpoly
+	url = https://github.com/jonathf/numpoly

CHANGELOG.rst

@@ -1,16 +1,22 @@
 Master Branch
 =============
 
+Version 4.2.0 (2020-11-23)
+==========================
+
 ADDED:
   * `include_axis_dim` flag added to `Distribution.sample` to force the
     inclusion of extra dimension. (Currently first dimension is omitted is
     `len(dist) == 1`.)
+  * Code of conduct and contribution descriptions in repo root.
+  * Tutorial for doing sequential polynomial chaos kriging.
 CHANGED:
   * `chaospy.E_cond` changed to accept simple polynomials as second argument,
     allowing for e.g. `chaospy.E_cond(q0*q1, q0, dist)` which can be
     interpreted as "expectation of `q0*q1` given `q0` with respect to `dist`".
   * Bugfixes to `chaospy.Spearman`
-  * Updates to the documentation.
+  * Full refactorization of the documentation.
+  * Updates `numpoly` to version 1.1.0. (some small breaking changes).
 REMOVED:
   * Deprecated `report_on_exception`. Caused recursion problems, and only a
     semi-useful diagnostic tool to begin with.

CONTRIBUTING.rst

@@ -0,0 +1,65 @@
+Contributing guidelines
+=======================
+
+Any kind of contribution to `chaospy` is very much welcome. Everything from
+simple comments or question to a full fledged `pull request
+<https://help.github.com/articles/about-pull-requests/>`_.
+
+A contribution can be one of the following cases:
+
+#. you have a question about usage;
+#. you think you may have found a bug (including unexpected behavior);
+#. you want to make some kind of change to the code base (e.g. to fix a bug, to
+   add a new feature, to update documentation).
+
+The sections below outline the steps in each case.
+
+You have a question about usage
+-------------------------------
+
+#. Use the search functionality `here
+   <https://github.com/jonathf/chaospy/issues>`_ to see if someone already
+   filed an issue on the same topic;
+#. If your issue search did not yield any relevant results, make a new issue;
+#. Choose the "Usage Question" template, and fill in the appropriate fields.
+
+You think you may have found a bug
+----------------------------------
+
+#. Use the search functionality `here
+   <https://github.com/jonathf/chaospy/issues>`_ to see if someone already
+   filed the same issue;
+#. If your issue search did not yield any relevant results, make a new issue;
+#. Choose the "Bug report" template, and fill in the appropriate fields.
+   Make sure to provide enough information to the rest of the community to
+   understand the cause and context of the problem.
+
+You want to make some kind of change to the code base
+-----------------------------------------------------
+
+#. Make an issue `here <https://github.com/jonathf/chaospy/issues>` and use the
+   "Functionality Request" template.
+   Announce your plan to the community *before you start working*.
+   Note in the issue that you are willing to make the proposed changes yourself.
+#. Wait until a maintainer comments and tells you the idea is approved for
+   implementation;
+#. If needed, fork the repository to your own Github profile and create your
+   own feature branch off of the latest master commit. While working on your
+   feature branch, make sure to stay up to date with the master branch by
+   rebasing changes on top, possibly from the 'upstream' repository (follow the
+   instructions `here
+   <https://help.github.com/articles/configuring-a-remote-for-a-fork/>`_ and
+   `here <https://help.github.com/articles/syncing-a-fork/>`_);
+#. Make sure the existing tests still work;
+#. Add your own tests (if necessary);
+#. Update or expand the documentation;
+#. `Push <http://rogerdudler.github.io/git-guide/>`_ your feature branch to
+   (your fork of) the Chaospy repository on GitHub;
+#. Create the pull request, e.g. following the instructions `here
+   <https://help.github.com/articles/creating-a-pull-request/>`_.
+
+In case you feel like you've made a valuable contribution, but you don't know
+how to write or run tests for it, or how to generate the documentation: don't
+let this discourage you from making the pull request; we can help you! Just go
+ahead and submit the pull request, but keep in mind that you might be asked to
+append additional commits to your pull request.

README.rst

@@ -16,31 +16,31 @@
 .. |pypi| image:: https://img.shields.io/pypi/v/chaospy
     :target: https://pypi.org/project/chaospy
 .. |binder| image:: https://mybinder.org/badge_logo.svg
-    :target: https://mybinder.org/v2/gh/jonathf/chaospy/master?filepath=docs%2Fnotebooks
+    :target: https://mybinder.org/v2/gh/jonathf/chaospy/master?filepath=docs%2Ftutorials
 
 Chaospy is a numerical tool for performing uncertainty quantification using
 polynomial chaos expansions and advanced Monte Carlo methods implemented in
 Python.
 
 * `Documentation <https://chaospy.readthedocs.io/en/master>`_
-* `Interactive tutorials with Binder <https://mybinder.org/v2/gh/jonathf/chaospy/master?filepath=docs%2Fnotebooks>`_
+* `Interactive tutorials with Binder <https://mybinder.org/v2/gh/jonathf/chaospy/master?filepath=docs%2Ftutorials>`_
 * `Source code <https://github.com/jonathf/chaospy>`_
 * `Issue tracker <https://github.com/jonathf/chaospy/issues>`_
+* `Code of Conduct <https://github.com/jonathf/chaospy/blob/master/CODE_OF_CONDUCT.md>`_
+* `Contribution Guideline <https://github.com/jonathf/chaospy/blob/master/CONTRIBUTING.md>`_
+* `Changelog <https://github.com/jonathf/chaospy/blob/master/CHANGELOg.md>`
 
 Installation
 ------------
 
-Installation should be straight forward from `PyPI <https://pypi.org/>`_:
+Installation should be straight forward using `pip <https://pypi.org/>`_:
 
 .. code-block:: bash
 
     $ pip install chaospy
 
-Or alternatively using `Conda <https://conda.io/>`_:
-
-.. code-block:: bash
-
-    $ conda install -c conda-forge chaospy
+For more installation details, see the `installation guide
+<https://chaospy.readthedocs.io/en/master/installation.html>`.
 
 Example Usage
 -------------
@@ -137,78 +137,3 @@ For more extensive guides on this approach an others, see the `tutorial
 collection`_.
 
 .. _tutorial collection: https://chaospy.readthedocs.io/en/master/tutorials
-
-Contributions and Related Projects
-----------------------------------
-
-A few shout-outs to people who have contributed to the Chaospy project:
-
-+--------------+--------------------------------------------------------------+
-| `OpenTURNS`_ | Thanks to `Régis Lebrun`_ for both proposing a collaboration |
-|              | and creating an initial implementation of both               |
-|              | `Chaospy Compatibility`_ in `OpenTURNS`_ and                 |
-|              | `OpenTURNS Compatibility`_ in ``chaospy``.                   |
-+--------------+--------------------------------------------------------------+
-| `orthopy`_   | Thanks to `Nico Schlömer`_ for providing the implementation  |
-| `quadpy`_    | for several of the quadrature integration methods.           |
-+--------------+--------------------------------------------------------------+
-| ``UQRF``     | Thanks to `Florian Künzner`_ for providing the initial       |
-|              | implementation of kernel density estimation and              |
-|              | quantity-of-interest distribution.                           |
-+--------------+--------------------------------------------------------------+
-
-.. _OpenTURNS: http://openturns.github.io/openturns/latest
-.. _Régis Lebrun: https://github.com/regislebrun
-.. _Chaospy Compatibility: http://openturns.github.io/openturns/latest/user_manual/_generated/openturns.ChaospyDistribution.html
-.. _OpenTURNS Compatibility: https://chaospy.readthedocs.io/en/master/recipes/external.html#module-chaospy.external.openturns_
-.. _orthopy: https://github.com/nschloe/orthopy
-.. _quadpy: https://github.com/nschloe/quadpy
-.. _Nico Schlömer: https://github.com/nschloe
-.. _Florian Künzner: https://github.com/flo2k
-
-Chaospy is being used in other related projects that requires uncertainty
-quantification components ``chaospy`` provides. For example:
-
-+-----------------+-----------------------------------------------------------+
-| `easyVVUQ`_     | Library designed to facilitate verification, validation   |
-|                 | and uncertainty quantification.                           |
-+-----------------+-----------------------------------------------------------+
-| `STARFiSh`_     | Shell-based, scientific simulation program                |
-|                 | for blood flow in mammals.                                |
-+-----------------+-----------------------------------------------------------+
-| `Profit`_       | Probabilistic response model fitting via interactive      |
-|                 | tools.                                                    |
-+-----------------+-----------------------------------------------------------+
-| `UncertainPy`_  | Uncertainty quantification and sensitivity analysis,      |
-|                 | tailored towards computational neuroscience.              |
-+-----------------+-----------------------------------------------------------+
-| `SparseSpACE`_  | Spatially adaptive combination technique targeted to      |
-|                 | solve high dimensional numerical integration.             |
-+-----------------+-----------------------------------------------------------+
-
-.. _easyVVUQ: https://github.com/UCL-CCS/EasyVVUQ
-.. _STARFiSh: https://www.ntnu.no/starfish
-.. _Profit: https://github.com/redmod-team/profit
-.. _UncertainPy: https://github.com/simetenn/uncertainpy
-.. _SparseSpACE: https://github.com/obersteiner/sparseSpACE
-
-For a more comprehensive list, see `Github's dependency graph
-<https://github.com/jonathf/chaospy/network/dependents>`_.
-
-Questions and Contributions
----------------------------
-
-Please feel free to
-`file an issue <https://github.com/jonathf/chaospy/issues>`_ for:
-
-* bug reporting
-* asking questions related to usage
-* requesting new features
-* wanting to contribute with code
-
-If you are going to publish work using this software, then please cite the
-article: `Chaospy: An open source tool for designing methods of uncertainty
-quantification <http://dx.doi.org/10.1016/j.jocs.2015.08.008>`_.
-In addition, if you deal with stochastic dependencies, please also cite:
-`Multivariate Polynomial Chaos Expansions with Dependent Variables
-<https://epubs.siam.org/doi/10.1137/15M1020447>`_.

chaospy/descriptives/__init__.py

@@ -1,39 +1,4 @@
-"""
-Descriptives are a collection of statistical analysis tools that can be used to
-analyse distributions and polynomials, both as an expansion (see
-:ref:`orthogonality`) and as results. For example, the expected value operator
-:func:`~chaospy.descriptives.expected.E` can be applied on distributions
-directly as follows::
-
-    >>> distribution = chaospy.Uniform(0, 1)
-    >>> expected = chaospy.E(distribution)
-    >>> expected
-    array(0.5)
-
-For multivariate distributions::
-
-    >>> distribution = chaospy.J(
-    ...     chaospy.Uniform(0, 1),
-    ...     chaospy.Normal(0, 1)
-    ... )
-    >>> expected = chaospy.E(distribution)
-    >>> expected
-    array([0.5, 0. ])
-
-
-For simple polynomials, distribution goes as the second argument. In other
-words, it calculates the expected value of the unit variable with respect to
-distribution. For example::
-
-    >>> distribution = chaospy.J(
-    ...     chaospy.Uniform(0, 1),
-    ...     chaospy.Normal(0, 1)
-    ... )
-    >>> q0, q1 = chaospy.variable(2)
-    >>> expected = chaospy.E(q1, distribution)
-    >>> expected
-    array(0.)
-"""
+"""Collection of descriptive statistics."""
 from .expected import E
 from .conditional import E_cond
 from .covariance import Cov

chaospy/descriptives/conditional.py

@@ -10,7 +10,7 @@
 
 def E_cond(poly, freeze, dist, **kws):
     """
-    Conditional expected value operator.
+    Conditional expected value of a distribution or polynomial.
 
     1st order statistics of a polynomial on a given probability space
     conditioned on some of the variables.

chaospy/descriptives/covariance.py

@@ -8,7 +8,7 @@
 
 def Cov(poly, dist=None, **kws):
     """
-    Covariance matrix, or 2rd order statistics.
+    Variance/Covariance matrix of a distribution or polynomial array.
 
     Args:
         poly (numpoly.ndpoly, Distribution) :

chaospy/descriptives/expected.py

@@ -5,7 +5,7 @@
 
 def E(poly, dist=None, **kws):
     """
-    Expected value operator.
+    The expected value of a distribution or polynomial.
 
     1st order statistics of a probability distribution or polynomial on a given
     probability space.