Update documentation for release 2.0

Author: olivhoenen

README.md

@@ -1,8 +1,8 @@
 # IMAS-Python
 
-IMAS-Python is a pure-python library to handle arbitrarily nested data structures.
-It is designed for, but not necessarily bound to, interacting with Interface 
-Data Structures (IDSs) as defined by the Integrated Modelling & Analysis Suite (IMAS) 
+IMAS-Python (formerly known as IMASPy its for versions < 2) is a pure-python library to handle 
+arbitrarily nested data structures. It is designed for, but not necessarily bound to, interacting 
+with Interface Data Structures (IDSs) as defined by the Integrated Modelling & Analysis Suite (IMAS) 
 Data Model.
 
 

docs/source/changelog.rst

@@ -9,7 +9,7 @@ What's new in IMAS-Python 2.0.0
 Breaking change
 '''''''''''''''
 
-The package name was changed from ``imaspy`` to ``imas`` while porting the code to GitHub. This shall only affect the import statements in your code. 
+The package name was changed from ``imaspy`` to ``imas`` while porting the code to `GitHub <https://github.com/iterorganization/IMAS-Python>`__. This shall only affect the import statements in your code. 
 
 New features and improvements
 '''''''''''''''''''''''''''''
@@ -23,7 +23,7 @@ New features and improvements
 - Updating the README, CONTRIBUTING guidelines and documentation after making the code open access.
 
 
-What's new in IMAS-Python 1.2.0
+What's new in IMASPy 1.2.0
 -------------------------------
 
 New features and improvements
@@ -43,7 +43,7 @@ Bug fixes
 
 
 
-What's new in IMAS-Python 1.1.1
+What's new in IMASPy 1.1.1
 -------------------------------
 
 This is a small release that mainly fixes issues related to the recent Data
@@ -59,7 +59,7 @@ Bug fixes
     Dictionary 4.0.0 and 3.42.0. In other cases, the Data Dictionary version is
     now explicitly indicated.
 
-- :issue:`IMAS-5560`: Fix a bug where IMAS-Python would not correctly recognize that
+- :issue:`IMAS-5560`: Fix a bug where IMASPy would not correctly recognize that
   the UDA backend is used.
 - :issue:`IMAS-5541`: Fix a bug when converting a closed contour to Data
   Dictionary version 4.0.0.
@@ -69,15 +69,15 @@ Bug fixes
   recent Data Dictionary version than the on-disk data was stored with.
 
 
-What's new in IMAS-Python 1.1
+What's new in IMASPy 1.1
 -----------------------------
 
 New features
 ''''''''''''
 
 - :ref:`1.1/improved performance`.
 - :ref:`1.1/improved conversion`.
-- IMAS-Python 1.1 adds support for Identifiers defined by the Data Dictionary. This
+- IMASPy 1.1 adds support for Identifiers defined by the Data Dictionary. This
   functionality is described in detail in :ref:`Identifiers`.
 - Support for the new
   :py:const:`~imas.ids_defs.FLEXBUFFERS_SERIALIZER_PROTOCOL` that is
@@ -92,7 +92,7 @@ New features
   netCDF file, which can be used for sharing and/or archiving data.
 
   This feature is in `preview` status, meaning that it may change in upcoming
-  minor releases of IMAS-Python.
+  minor releases of IMASPy.
 
 - Additional utility functions in :py:mod:`imas.util`:
 
@@ -111,18 +111,18 @@ New features
   - :py:func:`imas.util.get_data_dictionary_version` returns the Data
     Dictionary version for which an IDS was created.
 
-- Add support for IMAS Access Layer Core 5.2 and later. IMAS-Python can now be used
+- Add support for IMAS Access Layer Core 5.2 and later. IMASPy can now be used
   with just the Access Layer Core package available, the full AL-Python HLI is
   no longer required.
 
   Since the Access Layer Core is now installable with ``pip`` as well (requires
   access to the git repository on
-  `<https://github.com/iterorganization/imas-core>`__), you can install
-  ``imas`` and ``imas_core`` in one go with:
+  `<https://git.iter.org/projects/IMAS/repos/al-core/>`__), you can install
+  ``imaspy`` and ``imas_core`` in one go with:
 
   .. code-block:: bash
 
-    pip install 'imas[imas-core] @ git+ssh://[email protected]/iterorganization/imas-core.git'
+    pip install 'imaspy[imas-core] @ git+ssh://[email protected]/iterorganization/imaspy.git'
 
 - A diff tool for IDSs: :py:func:`imas.util.idsdiff`.
 - Implement ``==`` equality checking for IDS Structures and Arrays of Structures
@@ -131,12 +131,12 @@ New features
   backend.
 
   During a :py:meth:`~imas.db_entry.DBEntry.get` or
-  :py:meth:`~imas.db_entry.DBEntry.get_slice`, IMAS-Python first reads the version
+  :py:meth:`~imas.db_entry.DBEntry.get_slice`, IMASPy first reads the version
   of the Data Dictionary that was used to store the IDS. When this version is
-  not known to IMAS-Python, an error is raised. This error can now be ignored by
+  not known to IMASPy, an error is raised. This error can now be ignored by
   setting the parameter
   :py:param:`~imas.db_entry.DBEntry.get.ignore_unknown_dd_version` to
-  ``True``, and IMAS-Python will do its best to load the data anyway.
+  ``True``, and IMASPy will do its best to load the data anyway.
 
 - A new command line tool exists for analyzing which Data Dictionary fields are
   used in provided Data Entries. This tool is explained in detail in
@@ -150,7 +150,7 @@ Breaking changes
 
 .. note::
 
-  We attempt to keep the public API of IMAS-Python stable with minor releases. The
+  We attempt to keep the public API of IMASPy stable with minor releases. The
   following breaking change is the result of an upgrade of the IMAS Access Layer.
 
 - Starting with Access Layer 5.2 or newer, the Access Layer will raise
@@ -161,8 +161,8 @@ Breaking changes
   You may need to update the :py:class:`Exception` classes in ``try/except``
   blocks to the new Exception classes raised by ``imas_core``.
 
-  When using an older version of the Access Layer, the behaviour of IMAS-Python is no
-  different than in IMAS-Python 1.0.
+  When using an older version of the Access Layer, the behaviour of IMASPy is no
+  different than in IMASPy 1.0.
 
 
 Bug fixes
@@ -176,10 +176,10 @@ Bug fixes
 - Fixed a bug with :py:func:`~imas.ids_toplevel.IDSToplevel.serialize` when
   the IDS is in a non-default Data Dictionary version.
 - Fixed a bug when assigning ``nan`` to a FLT_0D, which would lead to a
-  confusing and incorrect log message in IMAS-Python 1.0.
-- Fixed incorrect oldest supported DD version. Previously IMAS-Python indicated that
+  confusing and incorrect log message in IMASPy 1.0.
+- Fixed incorrect oldest supported DD version. Previously IMASPy indicated that
   DD ``3.21.1`` was supported, however ``3.22.0`` is the oldest Data Dictionary
-  tested (and provided) with IMAS-Python. :py:attr:`imas.OLDEST_SUPPORTED_VERSION`
+  tested (and provided) with IMASPy. :py:attr:`imas.OLDEST_SUPPORTED_VERSION`
   has been updated to reflect this.
 - Fixed a bug when using numpy functions, such as
   :external:py:func:`numpy.isclose` on scalar numbers. Previously an error was
@@ -198,11 +198,11 @@ Improved performance
 ''''''''''''''''''''
 
 - Improved performance of :py:meth:`~imas.ids_toplevel.IDSToplevel.validate`.
-- Improved creation of IMAS-Python IDS objects. This made filling IDSs and loading
+- Improved creation of IMASPy IDS objects. This made filling IDSs and loading
   them with :py:meth:`~imas.db_entry.DBEntry.get` /
   :py:meth:`~imas.db_entry.DBEntry.get_slice` 10-20% faster.
 - Improved the performance of lazy loading. This is most noticeable with the
-  ``HDF5`` backend, which is now up to 40x faster than with IMAS-Python 1.0.
+  ``HDF5`` backend, which is now up to 40x faster than with IMASPy 1.0.
 - Improved the performance of :py:meth:`~imas.db_entry.DBEntry.get` /
   :py:meth:`~imas.db_entry.DBEntry.get_slice` /
   :py:meth:`~imas.db_entry.DBEntry.put` /
@@ -220,7 +220,7 @@ Converting IDSs between Data Dictionary versions has several improvements for
 recent DD versions. Further details on IDS conversion can be found in
 :ref:`Conversion of IDSs between DD versions`.
 
-- The IMAS-Python Command Line Interface for converting Data Entries between different
+- The IMASPy Command Line Interface for converting Data Entries between different
   versions of the Data Dictionary has been improved. See :ref:`Command line tool
   reference` or execute ``imas convert --help`` in a shell for further
   details.
@@ -230,7 +230,7 @@ recent DD versions. Further details on IDS conversion can be found in
   For example, in the ``pulse_schedule`` IDS, the node
   ``ec/beam/power_launched/reference`` in Data Dictionary ``3.40.0`` was renamed
   from ``ec/launcher/power/reference/data`` in Data Dictionary ``3.39.0``. This
-  use case is now supported by IMAS-Python.
+  use case is now supported by IMASPy.
 
 - Automatically convert data between 0D and 1D when possible (`IMAS-5170
   <https://jira.iter.org/browse/IMAS-5170>`__).

docs/source/index.rst

@@ -11,6 +11,11 @@ data structures. IMAS-Python is designed for, but not necessarily bound to,
 interacting with Interface Data Structures (IDSs) as defined by the
 Integrated Modelling & Analysis Suite (IMAS) Data Model.
 
+.. note::
+
+    IMAS-Python was formerly known as IMASPy, and was renamed with the release
+    of the major version 2. 
+
 It provides:
 
 - An easy-to-install and easy-to-get started package by

docs/source/installing.rst

@@ -56,7 +56,7 @@ This is how to run the IMAS-Python test suite:
     # inside the IMAS-Python git repository
     pytest imas --mini
 
-    # run with a specific backend
+    # run with a specific backend, requires IMAS-Core installed
     pytest imas --ascii --mini
 
 And to build the IMAS-Python documentation, execute:

docs/source/intro.rst

@@ -95,7 +95,7 @@ Load and store an IDS to disk with IMAS-Core
       :py:meth:`~imas.db_entry.DBEntry.put_slice` and
       :py:meth:`~imas.db_entry.DBEntry.get_sample` (with IMAS-Core>=5.4).
     - If you can't have access to it, you can save IDS to disk with the built-in
-      netCDF backend :ref:`Store and load an IDS to disk with netCDF`
+      netCDF backend :ref:`Load and store an IDS to disk with netCDF`
 
 To store an IDS to disk, we need to indicate the following URI to the
 IMAS-Core: ``imas:<backend>?path=<path_to_folder>`` or using the legacy query keys
@@ -129,8 +129,10 @@ can use ``<IDS>.get()`` to load IDS data from disk:
     >>> print(core_profiles2.ids_properties.comment.value)
 
 
-Load and store an IDS to disk with IMAS-Core
-''''''''''''''''''''''''''''''''''''''''''''
+.. _`Load and store an IDS to disk with netCDF`:
+
+Load and store an IDS to disk with netCDF
+'''''''''''''''''''''''''''''''''''''''''
 
 In IMAS-Python you do this as follows: