sphinx templates, removed mpi4py from extras (NeuralEnsemble#355)

* doc class template * Update doc/developers_guide.rst * fixed statistics docs * removed mpi4py from extras * info how to install and use mpi Co-authored-by: Michael Denker <m.denker@fz-juelich.de>
INM-6 · Oct 30, 2020 · d6efd2c · d6efd2c
1 parent bb83045
commit d6efd2c
Show file tree

Hide file tree

Showing 17 changed files with 146 additions and 330 deletions.
diff --git a/.gitignore b/.gitignore
@@ -45,8 +45,6 @@ lib64
 # sphinx build directory
 doc/_build
 doc/reference/toctree/*
-!doc/reference/toctree/asset/elephant.asset.ASSET.rst
-!doc/reference/toctree/kernels
 *.h5
 # setup.py dist directory
 dist

diff --git a/.travis.yml b/.travis.yml
@@ -26,7 +26,9 @@ matrix:
       python: 3.6
       env: DISTRIB="pip"
       before_install: sudo apt install -y libopenmpi-dev openmpi-bin
-      before_script: pip install -r requirements/requirements-extras.txt
+      before_script:
+        - pip install -r requirements/requirements-extras.txt
+        - pip install mpi4py
       script: mpiexec -n 1 python -m mpi4py.futures -m nose --with-coverage --cover-package=elephant
       after_success: coveralls || echo "coveralls failed"
 
@@ -51,6 +53,7 @@ matrix:
         - pip install -r requirements/requirements-docs.txt
         - pip install -r requirements/requirements-tutorials.txt
         - pip install -r requirements/requirements-extras.txt
+        - pip install mpi4py
         - sed -i -E "s/nbsphinx_execute *=.*/nbsphinx_execute = 'always'/g" doc/conf.py
       script: cd doc && make html
 
@@ -64,9 +67,9 @@ install:
       conda config --set always_yes yes;
       conda update conda;
       sed -i "s/python>=[0-9]\.[0-9]/python=${TRAVIS_PYTHON_VERSION}/g" requirements/environment.yml;
+      sed -i '/mpi4py/d' requirements/environment.yml;
       conda env create -f requirements/environment.yml;
       conda activate elephant;
-      conda uninstall -y mpi4py;
       pip list;
     else
       pip install -r requirements/requirements.txt;

diff --git a/doc/_templates/autosummary/class.rst b/doc/_templates/autosummary/class.rst
@@ -0,0 +1,31 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :inherited-members:
+   :special-members: __call__
+
+   {% block methods %}
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/doc/developers_guide.rst b/doc/developers_guide.rst
@@ -4,8 +4,17 @@
 Developers' Guide
 =================
 
-.. note:: The documentation guide (how to write a good documentation, naming
-          conventions, docstring examples) is in :ref:`documentation_guide`.
+.. note::
+    1. The documentation guide (how to write a good documentation, naming
+       conventions, docstring examples) is in the :ref:`documentation_guide`.
+
+    2. We highly recommend to get in touch with us (see :ref:`get_in_touch`) *before* starting
+       to implement a new feature in Elephant. This way, we can point out synergies with
+       complementary efforts and help in designing your implementation such that its integration
+       into Elephant will be an easy process.
+
+    3. If you experience any problems during one of the steps below, please
+       contact us and we'll help you.
 
 
 1. Follow the instructions in :ref:`prerequisites` to setup a clean conda
@@ -23,12 +32,26 @@ Developers' Guide
     $ git clone git://github.com/<your-github-profile>/elephant.git
     $ cd elephant
 
-3. Install requirements.txt, (optionally) requirements-extras.txt, and
-   requirements-tests.txt::
+3. Install the requirements (either via pip or conda):
+
+.. tabs::
+
+    .. tab:: pip
+
+        .. code-block:: sh
+
+            pip install -r requirements/requirements.txt
+            pip install -r requirements/requirements-extras.txt  # optional
+            pip install -r requirements/requirements-tests.txt
+
+    .. tab:: conda
+
+        .. code-block:: sh
+
+            conda env create -f requirements/environment.yml
+            conda activate elephant
+            pip install -r requirements/requirements-tests.txt
 
-    $ pip install -r requirements/requirements.txt
-    $ pip install -r requirements/requirements-extras.txt  # optional
-    $ pip install -r requirements/requirements-tests.txt
 
 4. Before you make any changes, run the test suite to make sure all the tests
    pass on your system::
@@ -49,9 +72,9 @@ Developers' Guide
 
    * fixing a bug;
    * improving the documentation;
-   * adding a new functional.
+   * adding a new functionality.
 
-6. If it was a new functional, please write:
+6. If it is a new functionality, please write:
 
    - documentation (refer to :ref:`documentation_guide`);
    - tests to cover your new functions as much as possible.
@@ -69,7 +92,3 @@ Developers' Guide
 
 9. Open a `pull request <https://github.com/NeuralEnsemble/elephant/pulls>`_.
    Then we'll merge your code in Elephant.
-
-
-.. note:: If you experience a problem during one of the steps above, please
-          contact us by :ref:`get_in_touch`.
diff --git a/doc/install.rst b/doc/install.rst
@@ -13,24 +13,24 @@ Below is the explanation of how to proceed with these two steps.
 Prerequisites
 =============
 
-Elephant requires Python_ 2.7, 3.5, 3.6, 3.7, or 3.8.
+Elephant requires `Python <http://python.org/>`_ 2.7, 3.5, 3.6, 3.7, or 3.8.
 
 .. tabs::
 
 
     .. tab:: (recommended) Conda (Linux/MacOS/Windows)
 
-        1. Create your conda environment (e.g., `elephant_env`):
+        1. Create your conda environment (e.g., `elephant`):
 
            .. code-block:: sh
 
-              conda create --name elephant_env python=3.7 numpy scipy tqdm
+              conda create --name elephant python=3.7 numpy scipy tqdm
 
         2. Activate your environment:
 
            .. code-block:: sh
 
-              conda activate elephant_env
+              conda activate elephant
 
 
     .. tab:: Debian/Ubuntu
@@ -51,12 +51,20 @@ Installation
 
     .. tab:: Stable release version
 
-        The easiest way to install Elephant is via pip_:
+        The easiest way to install Elephant is via `pip <http://pypi.python.org/pypi/pip>`_:
 
            .. code-block:: sh
 
               pip install elephant
 
+        If you want to use advanced features of Elephant, install the package
+        with extras:
+
+           .. code-block:: sh
+
+              pip install elephant[extras]
+
+
         To upgrade to a newer release use the ``--upgrade`` flag:
 
            .. code-block:: sh
@@ -70,12 +78,6 @@ Installation
 
               pip install --user elephant
 
-        To install Elephant with all extra packages, do:
-
-           .. code-block:: sh
-
-              pip install elephant[extras]
-
 
     .. tab:: Development version
 
@@ -95,42 +97,62 @@ Installation
 
               git clone git://github.com/NeuralEnsemble/elephant.git
               cd elephant
-              pip install -e .
 
+        .. tabs::
+
+            .. tab:: Minimal setup
+
+                .. code-block:: sh
+
+                    pip install -e .
+
+
+            .. tab:: conda (with extras)
+
+                .. code-block:: sh
+
+                    conda remove -n elephant --all  # remove the previous environment
+                    conda env create -f requirements/environment.yml
+                    conda activate elephant
+                    pip install -e .
+
+MPI support
+-----------
+
+Some Elephant modules (ASSET, SPADE, etc.) are parallelized to run with MPI.
+In order to make use of MPI parallelization, you need to install ``mpi4py``
+package:
+
+.. tabs::
+
+    .. tab:: conda (easiest)
+
+        .. code-block:: sh
+
+            conda install -c conda-forge mpi4py
+
+    .. tab:: pip (Debian/Ubuntu)
+
+        .. code-block:: sh
+
+            sudo apt install -y libopenmpi-dev openmpi-bin
+            pip install mpi4py
+
+To run a python script that supports MPI parallelization, run in a terminal:
+
+.. code-block:: sh
+
+    mpiexec -n numprocs python -m mpi4py pyfile [arg] ...
+
+For more information, refer to `mpi4py
+<https://mpi4py.readthedocs.io/en/stable/mpi4py.run.html>`_ documentation.
 
 
 Dependencies
 ------------
 
-The following packages are required to use Elephant (refer to requirements_ for the exact package versions):
-
-    * numpy_ - fast array computations
-    * scipy_ - scientific library for Python
-    * quantities_ - support for physical quantities with units (mV, ms, etc.)
-    * neo_ - electrophysiology data manipulations
-    * tqdm_ - progress bar
-    * six_ - Python 2 and 3 compatibility utilities
-
-These packages are automatically installed when you run ``pip install elephant``.
-
-The following packages are optional in order to run certain parts of Elephant:
-
-    * `pandas <https://pypi.org/project/pandas/>`_ - for the :doc:`pandas_bridge <reference/pandas_bridge>` module
-    * `scikit-learn <https://pypi.org/project/scikit-learn/>`_ - for the :doc:`ASSET <reference/asset>` analysis
-    * `nose <https://pypi.org/project/nose/>`_ - for running tests
-    * `numpydoc <https://pypi.org/project/numpydoc/>`_ and `sphinx <https://pypi.org/project/Sphinx/>`_ - for building the documentation
-
-These and above packages are automatically installed when you run ``pip install elephant[extras]``.
-
-.. _`Python`: http://python.org/
-.. _`numpy`: http://www.numpy.org/
-.. _`scipy`: https://www.scipy.org/
-.. _`quantities`: http://pypi.python.org/pypi/quantities
-.. _`neo`: http://pypi.python.org/pypi/neo
-.. _`pip`: http://pypi.python.org/pypi/pip
-.. _Anaconda: https://docs.anaconda.com/anaconda/install/
-.. _`Conda environment`: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html
-.. _`tqdm`: https://pypi.org/project/tqdm/
-.. _`six`: https://pypi.org/project/six/
-.. _requirements: https://github.com/NeuralEnsemble/elephant/blob/master/requirements/requirements.txt
-.. _PyPI: https://pypi.org/
+Elephant relies on the following packages (automatically installed when you
+run ``pip install elephant``):
+
+    * `quantities <http://pypi.python.org/pypi/quantities>`_ - support for physical quantities with units (mV, ms, etc.)
+    * `neo <http://pypi.python.org/pypi/neo>`_ - electrophysiology data manipulations
diff --git a/doc/reference/toctree/asset/elephant.asset.ASSET.rst b/doc/reference/toctree/asset/elephant.asset.ASSET.rst
diff --git a/doc/reference/toctree/kernels/elephant.kernels.AlphaKernel.rst b/doc/reference/toctree/kernels/elephant.kernels.AlphaKernel.rst