[DOC] move installation instructions to .rst

doc/source/conf.py

@@ -62,7 +62,7 @@
 
 # General information about the project.
 project = u"tofu"
-copyright = u"2016, Didier VEZINET"
+copyright = u"2016-2019, Tofu contributors"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -167,11 +167,12 @@
     "bootstrap_version": "3",
     "nosidebar": True,
     "navbar_links": [
-        ("Gallery", "auto_examples/index"),
         ("Installation", "installation"),
-        ("About us", "aboutus"),
-        ("Versions", "releases"),
-        ("Code doc", "tofu"),
+        ("Contributing", 'contributing'),
+        ("Gallery", "auto_examples/index"),
+        ("About", "aboutus"),
+        ("Releases", "releases"),
+        ("API", "tofu"),
     ],
 }
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,

doc/source/contributing.rst

@@ -0,0 +1,90 @@
+
+Contributing to tofu
+====================
+
+You found a bug, or you want to add something to the library ? This
+tutorial will show you how to get the repository and the first steps to
+contribute to the project.
+
+There are many tools and concepts to get familiar with when contributing
+to an **open-source python library**. A good place to get started is the
+`scikit-project <https://github.com/nathanshammah/scikit-project>`__.
+And here is a list of tools you should get familiar with:
+
+-  ``Python``: the main language of **tofu**
+-  ``IPython``: powerful interactive shell for python, and check this
+   `tutorial <https://ipython.org/ipython-doc/3/interactive/tutorial.html>`__
+-  ``git``, and the `feature branch
+   workflow <https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow>`__
+-  ``github``: follow and watch `our
+   project <https://github.com/ToFuProject/tofu>`__
+-  A text editor: ``emacs``, ``vim``, ``sublime``, or whichever you want
+
+
+We will use Miniconda (light version of Anaconda, but you can also work
+with Anaconda or another python package manager of your choice) not only
+to install and manage the packages necessary for installing ToFu, but
+also to have a working bash-like Terminal.
+
+-  `Get the latest version and install
+   it. <https://docs.conda.io/en/latest/miniconda.html>`__
+-  Follow the directions (you can use default options)
+
+We are going to create an environment specific for ToFu.
+
+::
+
+   $ conda create -n tofu3 python scipy numpy cython git ipython
+   $ conda activate tofu3
+
+This creates a conda environment named "tofu3" and installs scipy,
+numpy, git, ipython and cython. The second command activates this
+environment.
+
+-  Create a ssh public key and add it to your GitHub account: `follow
+   this
+   tutorial. <https://help.github.com/en/articles/adding-a-new-ssh-key-to-your-github-account>`__
+-  Go to ToFu's GitHub repository:
+   `here. <https://github.com/ToFuProject/tofu/>`__
+-  Click on "clone or download" and swith to the option "Use SSH". Copy
+   the link.
+-  Move to where you would like to install ToFu ``$ cd some_path``
+-  ``$ git clone git@github.com:ToFuProject/tofu.git`` (make sure you
+   remember the path where you are installing, if you want to install it
+   into your home repository, just make sure to ``cd ~`` before the
+   ``git clone...``)
+
+
+-  Move to the tofu directory, probably: ``cd ~/tofu``
+-  Switch to the ``git`` branch you will be working on. If you are just
+   starting you probably want to start from the latest develop branch:
+   ``git checkout devel``. If you are not familiar with **git** take a
+   look at `this tutorial
+   (long) <https://www.atlassian.com/git/tutorials>`__ or `this short
+   one <https://rogerdudler.github.io/git-guide/>`__
+-  Compile ``python setup.py build_ext --inplace``
+-  Make sure tests are running ``nosetests``
+
+
+
+If you wish to contribute, but don't know where to start, check `our
+open issues <https://github.com/ToFuProject/tofu/issues>`__. You can
+also read `this
+tutorial <https://github.com/firstcontributions/first-contributions>`__,
+on how to contribute to a github project. Before modifying the code, you
+should create a new branch (based on the *devel* branch) and switch to it.
+
+::
+
+   git checkout -b <theNameOfYourBranch> # probably IssueNumber eg. Issue123
+   # change the source code
+   git add <files you changed>
+   git commit -m "[a tag] a message that explains what you changed"
+   git push -u origin <theNameOfYourBranch>
+
+Now you can open a pull request in our `github
+page <https://github.com/ToFuProject/tofu/pulls>`__, from your branch,
+``theNameOfYourBranch`` to ``devel``. We will review it, comment it, and
+accept it.
+
+

doc/source/index.rst

@@ -57,7 +57,9 @@ Contents:
    :maxdepth: 1
 
    How to install tofu <installation.rst>
-   All tutorials and examples <auto_examples/index.rst>
+   A guide to contributing to tofu <contributing.rst>
+   Tutorials and examples <auto_examples/index.rst>
+
 
 * How to create / handle a diagnostic geometry
    - Visit the basic_ tutorial for getting started: create, plot and save

doc/source/installation.rst

@@ -3,5 +3,143 @@
 Installing tofu
 ================
 
-.. raw:: html
-	 :file: installation_tabs_source.html
+As of October 2019, `tofu` is still under heavy development. Therefore, installation
+instructions are provided officialy for Linux and ITER users. However, instructions
+for other platforms are also provided since they have been known to work out for some users.
+If installation fails for your use-case, please open an issue over
+at `Github. <https://github.com/ToFuProject/tofu/>`__ so that we can try adressing it.
+
+-  :ref:`installing-tofu-on-linux`
+-  :ref:`installing-tofu-on-mac`
+-  :ref:`installing-tofu-on-windows`
+-  :ref:`iter-users`
+-  :ref:`installing-as-a-developer`
+
+
+.. _installing-tofu-on-linux:
+
+Linux
+-----
+
+To install and use `tofu` on Linux, we recommend to proceed in two steps: install the
+Python package manager conda and then install tofu.
+We recommend ``Miniconda`` (light version of the Anaconda Python distribution for data science,
+but you can also work with ``pip`` or another Python package manager of
+your choice).
+
+-  `Get the latest Miniconda version and install
+   it. <https://docs.conda.io/en/latest/miniconda.html>`__
+- Install tofu
+
+::
+
+   $ conda install -c tofuproject tofu
+
+- Check that tofu works by printing its version number:
+
+::
+
+   python -c "import tofu; print(tofu.__version__)"
+
+Now you can `follow a tutorial. <auto_examples/index.html>`__
+
+.. _installing-tofu-on-mac:
+
+Mac OS X
+--------
+
+See :ref:`installing-as-a-developer`.
+
+.. _installing-tofu-on-windows:
+
+Windows
+-------
+
+See :ref:`installing-as-a-developer`.
+
+Additional *caveat*: you may need to open an ``Anaconda prompt`` (usually found by pressing
+the Windows key) to run the commands described in the linked section.
+
+
+.. _iter-users:
+
+Using tofu on a ITER cluster
+----------------------------
+
+If you have an **ITER** account, you can use **tofu** directly from ITER
+Computing Cluster. No need to install tofu !
+
+-  Ask for access to ITER servers, if you don't have them already.
+-  For information about the cluster, see `this
+   link. <https://confluence.iter.org/display/IMP/ITER+Computing+Cluster>`__
+-  Open a new terminal and connect to server (see link above)
+-  Create a new file in your ``$HOME`` directory, you can name it
+   ``load_tofu_modules.sh``
+-  Open it and add the following lines:
+
+::
+
+   module refresh
+   source /etc/profile.d/modules.sh # make sure you have the module environment
+   module purge # unload any previously loaded modules
+   module load IMAS/3.24.0-4.1.5 # for IMAS data base
+   module load IPython/6.3.1-intel-2018a-Python-3.6.4 # for iPython
+   module load PySide2/5.12.0-intel-2018a-Python-3.6.4
+   module load ToFu/1.4.0-intel-2018a-Python-3.6.4 # Load tofu :)
+
+-  Convert it to an executable, from the terminal:
+   ``chmod +x ~/load_tofu_modules.sh``
+-  Execute it: ``./load_tofu_modules.sh``
+-  If you are going to use *tofu* often, you might want to add the
+   execution of the script to your ``.bash_profile`` (or ``.bashrc``
+   file):
+
+::
+
+   echo './load_tofu_modules.sh' >> .bash_profile
+
+You are all set, open a Python/IPython console and try importing tofu.
+
+::
+
+   $ python
+   In [1]: import tofu as tf
+
+You can now `follow a tutorial. <auto_examples/index.html>`__
+
+
+.. _installing-as-a-developer:
+
+Installing tofu as a developer
+------------------------------
+
+To install tofu as a developer, we recommend using the conda ecosystem (Miniconda in particular):
+
+-  `Get the latest Miniconda version and install
+   it. <https://docs.conda.io/en/latest/miniconda.html>`__
+
+- create a dedicated (Python 3) environment for tofu development and activate it
+
+::
+
+   $ conda create -n tofu3 python=3.6 scipy numpy cython git
+   $ conda activate tofu3
+
+-  Move to where you would like to install your local copy of ToFu ``$ cd some_path``
+-  ``$ git clone https://github.com/ToFuProject/tofu.git`` (make sure you
+   remember the path where you are installing, if you want to install it
+   into your home repository, just make sure to ``cd ~`` before the
+   ``git clone...``)
+-  Move to the "cloned" tofu directory that has been created by the git clone command:
+   ``cd ~/tofu``
+-  Switch to the ``git`` branch you will be working on. If you are just
+   starting you probably want to start from the latest develop branch:
+   ``git checkout devel``. If you are not familiar with **git** take a
+   look at `this tutorial
+   (long) <https://www.atlassian.com/git/tutorials>`__ or `this short
+   one <https://rogerdudler.github.io/git-guide/>`__
+-  Run ``pip install -e .[dev]``. This will install dependencies, compile the
+   tofu Cython extensions and install it into your conda environment while you can still
+   modify the source files in the current repository.`
+-  Make sure tofu tests are running by typing ``nosetests``
+

examples/tutorials/plot_basic_tutorial.py

@@ -5,9 +5,14 @@
 This is a tutorial that aims to get a new user a little familiar with tofu's
  structure.
 """
+
+# The following imports matplotlib, preferably using a
+# backend that allows the plots to be interactive (Qt5Agg).
 import matplotlib
-import matplotlib.pyplot as plt
-matplotlib.use('Qt5Agg')
+try:
+    matplotlib.use('Qt5Agg')
+except ImportError:
+    matplotlib.use(matplotlib.rcParams['backend'])
 
 ###############################################################################
 # We start by loading `tofu`. You might see some warnings at this stage since