diff --git a/doc/source/conf.py b/doc/source/conf.py index 68c38191d..82930885f 100644 --- a/doc/source/conf.py +++ b/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, diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst new file mode 100644 index 000000000..cbe3b8077 --- /dev/null +++ b/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 `__. +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 `__ +- ``git``, and the `feature branch + workflow `__ +- ``github``: follow and watch `our + project `__ +- 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. `__ +- 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. `__ +- Go to ToFu's GitHub repository: + `here. `__ +- 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) `__ or `this short + one `__ +- 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 `__. You can +also read `this +tutorial `__, +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 # probably IssueNumber eg. Issue123 + # change the source code + git add + git commit -m "[a tag] a message that explains what you changed" + git push -u origin + +Now you can open a pull request in our `github +page `__, from your branch, +``theNameOfYourBranch`` to ``devel``. We will review it, comment it, and +accept it. + + diff --git a/doc/source/index.rst b/doc/source/index.rst index 943865847..1a3da9a85 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -57,7 +57,9 @@ Contents: :maxdepth: 1 How to install tofu - All tutorials and examples + A guide to contributing to tofu + Tutorials and examples + * How to create / handle a diagnostic geometry - Visit the basic_ tutorial for getting started: create, plot and save diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 2d61fad35..db49d1a62 100644 --- a/doc/source/installation.rst +++ b/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. `__ 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. `__ +- 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. `__ + +.. _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. `__ +- 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. `__ + + +.. _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. `__ + +- 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) `__ or `this short + one `__ +- 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`` + diff --git a/examples/tutorials/plot_basic_tutorial.py b/examples/tutorials/plot_basic_tutorial.py index 14b2b4a85..57d49b04a 100644 --- a/examples/tutorials/plot_basic_tutorial.py +++ b/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