Update docs

doc/source/heterogeneous.rst

@@ -64,7 +64,7 @@ Heterogeneous neurites can be identified using the ``Neurite::is_heterogeneous``
 which would return ``[False, True, False]``, meaning the 2nd neurite extending from the soma contains multiple neurite types.
 
 
-Sub-neurite views of heterogeneous neurites
+sub-neurite views of heterogeneous neurites
 --------------------------------------------
 
 Default mode
@@ -84,14 +84,15 @@ For example:
 
     NeuriteType.basal_dendrite NeuriteType.basal_dendrite NeuriteType.apical_dendrite
 
-I.E. the axon-carrying dendrite would be treated as a basal dendrite.
+In other words, the axon-carrying dendrite would be treated as a basal dendrite.
+
 For feature extraction and checks, the axon-carrying dendrite is treated as a basal dendrite.
 Features, for which an axon neurite type is passed, do not have access to the axonal part of the neurite.
 For instance, the number of basal and axon neurites will be two and zero respectively.
-A features such as ``total_volume`` would include the entire axon-carrying dendrite, without separating between basal and axon types.
+A feature such as ``total_volume`` would include the entire axon-carrying dendrite, without separating between basal and axon types.
 
-Sub-neurite mode
-~~~~~~~~~~~~~~~~
+subtree mode
+~~~~~~~~~~~~
 
 The ``Population``, ``Morphology`` and ``Neurite`` objects have a boolean attribute named ``process_subtrees`` which is set to ``False`` by default.
 The value of this attribute can be set to ``True`` in order to take into account heterogeneous sub-neurites.
@@ -210,7 +211,7 @@ features.get
 .. warning::
     The ``features.get`` function can be used with either the ``neurite_type`` or the ``section_type`` parameter, depending on what type of object the feature is applied.
     When the feature is applied to a ``Population`` or to a ``Morphology`` object, only the ``neurite_type`` parameter is accepted.
-    While when the feature is applied to a ``Neurite`` or to a list of ``Neurite`` objects, only the ``section_type`` parameter is accepted.
+    While the feature is applied to a ``Neurite`` or to a list of ``Neurite`` objects, only the ``section_type`` parameter is accepted.
 
 Conventions & Incompatibilities
 -------------------------------

doc/source/migration.rst

@@ -29,6 +29,85 @@
 Migration guides
 =======================
 
+.. _migration-v4.0.0:
+
+Migration to v4 version
+-----------------------
+
+Deprecated modules
+~~~~~~~~~~~~~~~~~~
+
+The following modules have been deprecated:
+
+- ``neurom/core/neuron.py`` (use ``neurom/core/morphology.py``)
+- ``neurom/features/bifurcationfunc.py`` (use ``neurom/features/bifurcation.py``)
+- ``neurom/features/sectionfunc.py`` (use ``neurom/features/section.py``)
+- ``neurom/check/neuron_checks.py`` (use ``neurom/check/morphology_checks.py``)
+- ``neurom/viewer.py`` (use ``from neurom.view import plot_[morph|morph3d|dendrogram]``)
+
+Breaking changes in Morphology class
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Morphology class has changed in two major ways:
+
+* Does not derive from morphio.mut.Morphology
+* By default an immutable morphio Morphology is instantiated
+
+The morphio Morphology is stored as a protected attribute in neurom Morphology object turning
+the latter into a wrapper around morphio Morphology.
+
+However, it is still accessible via the ``to_morphio()`` method:
+
+.. testcode:: [v4-migration]
+
+    from neurom import load_morphology
+    neurom_morphology = load_morphology('tests/data/swc/Neuron.swc')
+    ref_morph = neurom_morphology.to_morphio()
+
+    print(type(ref_morph).__module__, type(ref_morph).__name__)
+
+.. testoutput:: [v4-migration]
+
+    morphio._morphio Morphology
+
+which means that the default morphio Morphology is immutable. It is however, possible to use a mutable morpio Morphology if needed:
+
+.. testcode:: [v4-migration]
+
+   import morphio.mut
+
+   morphio_morphology = morphio.mut.Morphology('tests/data/swc/Neuron.swc')
+   neurom_morphology = load_morphology(morphio_morphology)
+   ref_morph = neurom_morphology.to_morphio()
+
+   print(type(ref_morph).__module__, type(ref_morph).__name__)   
+
+.. testoutput:: [v4-migration]
+
+   morphio._morphio.mut Morphology
+
+
+To mutate a readonly morphology requires a detour through morphio's mutable object as follows:
+
+.. testcode:: [v4-migration]
+
+   from neurom.core import Morphology
+   from morphio import PointLevel, SectionType
+
+   morph = load_morphology('tests/data/swc/Neuron.swc')
+   mut = morph.to_morphio().as_mutable()
+
+   point_lvl = PointLevel([[0, 0, 0],[1, 1, 1]], [1, 1])
+   mut.append_root_section(point_lvl, SectionType.basal_dendrite)
+
+   mutated_morph = Morphology(mut)
+
+   print(len(morph.neurites), len(mutated_morph.neurites))
+
+.. testoutput:: [v4-migration]
+
+   4 5
+
 .. _migration-v3.0.0:
 
 Migration to v3 version