diff --git a/README.md b/README.md index b560cd262..8d4169f5c 100644 --- a/README.md +++ b/README.md @@ -100,68 +100,46 @@ If IMAS is not available, tofu will simply display a warning stating that the im tofu can thus easily load and handle multiple IDSs (IMAS data structure units) and provide command-line tools for exporting IMAS data to other general tofu classes (e.g.: Cameras, Plasma2D...) and for interactive plotting. All tofu objects have methods to facailitate in-python-console introspection, the ``__repr__`` method is overloaded to display relevant information, an dthis is widely used to explore the data loaded from IMAS. -Do you want to use **tofu** on IMAS and don't know where to start? [See our wiki.](https://github.com/ToFuProject/tofu/wiki/Using-tofu-on-IMAS-server) +Do you want to use **tofu** on IMAS and don't know where to start? +[See our documetation.](https://tofuproject.github.io/tofu/installation.html#using-tofu-on-a-iter-cluster) ---- ## Installing tofu - -### For Windows - - -- [Follow this link to know how to configure your Windows to code on ToFu !](https://github.com/ToFuProject/tofu/wiki/Installing-tofu-on-windows) - -### For Ubuntu / Mac +### For Ubuntu #### Standard mode ``` conda install -c tofuproject tofu ``` -#### Developer mode - -Install dependencies - - - python (>= 3.6) - numpy - scipy - matplotlib - cython >= 0.26 - nose - pygments - pandas - - -Checkout the tofu git repository and from the top directory - - - python setup.py build_ext --inplace - python setup.py install - - -## Getting Started - -See our wiki's page: [Getting started](https://github.com/ToFuProject/tofu/wiki/Getting-started) +## For Developers and other platforms +[See our documentation.](https://tofuproject.github.io/tofu/installation.html) ----- -**Licensing** +**Licensing** -It is distributed under the MIT license and aims at providing the fusion community with -a transparent and modular tool for creating / designing diagnostics and using them for -synthetic diagnostic (direct problem) and tomography (inverse problem). +It is distributed under the MIT license and aims at providing the fusion +community with a transparent and modular tool for creating / designing +diagnostics and using them for synthetic diagnostic (direct problem) +and tomography (inverse problem). **History** -It was first created at the Max-Planck Institute for Plasma Physics (IPP) in Garching, Germany, -by Didier Vezinet, and is now maintained / debugged / updated by a team of contributors. +It was first created at the Max-Planck Institute for Plasma Physics (IPP) +in Garching, Germany, by Didier Vezinet, and is now maintained, debugged +and updated by a team of contributors. ----- **Warning** This Pypi package focuses on tomography for fusion research. -It uses the same name as a previous package dedicated to a testing framework coupling fixtures and tests loosely, now renamed **reahl-tofu** and developped by Iwan Vosloo since 2006. If you ended up here looking for a web-oriented library, you should probably redirect to the more recent [**reahl-tofu**](https://pypi.python.org/pypi/reahl-tofu) page. +It uses the same name as a previous package dedicated to a testing framework +coupling fixtures and tests loosely, now renamed **reahl-tofu** and developped +by Iwan Vosloo since 2006. If you ended up here looking for a web-oriented +library, you should probably redirect to the more recent +[**reahl-tofu**](https://pypi.python.org/pypi/reahl-tofu) page. diff --git a/doc/source/conf.py b/doc/source/conf.py index 82930885f..45b3cc392 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -14,6 +14,7 @@ import sys import tofu as tf import sphinx_bootstrap_theme +from sphinx_gallery.sorting import FileNameSortKey # Getting tofu version tf_version = tf.__version__[:3] @@ -354,6 +355,8 @@ sphinx_gallery_conf = { "examples_dirs": "../../examples", # path to your example scripts "gallery_dirs": "auto_examples", # path to save gallery generated output + "within_subsection_order": FileNameSortKey, + 'filename_pattern': '/tuto_plot_', } diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index cbe3b8077..d49cafd61 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -1,11 +1,29 @@ +Contribute to tofu +================== -Contributing to tofu -==================== - -You found a bug, or you want to add something to the library ? This +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. +Bug reports and suggestions +---------------------------- + +If you found a bug in **tofu**, or if you have a suggestion, the best is to open +an issue directly on our `github page `_. +If you are opening an issue related to a bug found, please specify the version +of the librairies (**tofu**, python, etc.) you are using, any configuration +information that might be helpful to us (OS, server, how you installed +**tofu**), a minimal example to recreate the bug (if possible), and the log +files or errors you might have got. + + + +Developping in the code +----------------------- + +The basic tools +""""""""""""""" + 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 `__. @@ -66,12 +84,20 @@ environment. - Make sure tests are running ``nosetests`` +Where to start? +""""""""""""""" 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 +on how to contribute to a github project. + + +Git branches and pull requests +"""""""""""""""""""""""""""""" + +Before modifying the code, you should create a new branch (based on the *devel* branch) and switch to it. :: @@ -88,3 +114,23 @@ page `__, from your branch, accept it. + +Continuous integration +"""""""""""""""""""""" + +For each pull request (PR) on github, there will be a series of tests run to +make sure the modifications introduced to the library did not introduce any +errors. If all tests pass, you should see something like the image below. + +.. image:: images/travis.png + +If there is an error (red cross instead of green check) it can be either that +your code is breaking the normal functionning of the code, or (less probably) +that there is a bug in the unit tests. Please try and understand what went wrong. +If you cannot find the problem, you can ask for help by commenting on the PR. +Additionally to the unit tests, we have integrated pep8speaks_, a bot that will +check your coding style. + +.. _pep8speaks: https://pep8speaks.com/ + +.. image:: images/pep8speaks.png diff --git a/doc/source/images/pep8speaks.png b/doc/source/images/pep8speaks.png new file mode 100644 index 000000000..9c868082f Binary files /dev/null and b/doc/source/images/pep8speaks.png differ diff --git a/doc/source/images/travis.png b/doc/source/images/travis.png new file mode 100644 index 000000000..a85c75b39 Binary files /dev/null and b/doc/source/images/travis.png differ diff --git a/doc/source/index.rst b/doc/source/index.rst index 1a3da9a85..6f1532060 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -35,20 +35,25 @@ interactive plots.