Updated installation instructions with notes on NEURON install.

CHANGELOG

@@ -1,5 +1,9 @@
 # 3.6
 
+## 3.6.4
+
+* Slightly changed the `neuron` install workflow. NEURON is now pip installed
+
 ## 3.6.3
 
 * Updated "Getting Started" guide.

bsb/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "3.6.3"
+__version__ = "3.6.4"
 
 from .reporting import set_verbosity, report, warn

docs/source/usage/installation.rst

@@ -4,16 +4,60 @@ Istallation Guide
 
 The scaffold framework can be installed using Pip for Python 3
 
-  .. code-block:: bash
+.. code-block:: bash
 
-    pip3 install bsb
+    pip install bsb
 
 You can verify that the installation works with
 
-  .. code-block:: bash
+.. code-block:: bash
 
-    bsb -v=3 compile -x=200 -z=200 -p
+    bsb make-config
+    bsb -v=3 compile -x=50 -z=50 -p
 
-This should generate an HDF5 file in your current directory and open a plot of
-the generated network. If everything looks fine you are ready to advance to
-the next topic.
+This should generate a template config and an HDF5 file in your current directory and open
+a plot of the generated network, it should contain a column of ``base_type`` cells. If no
+errors occur you are ready to :doc:`get started <getting-started>`.
+
+
+Installing for NEURON
+=====================
+
+The BSB's installation will install NEURON from PyPI if no ``NEURON`` installation is
+detected by ``pip``. This means that any custom installations that rely on ``PYTHONPATH``
+to be detected at runtime but aren't registered as an installed package to pip will be
+overwritten. Because it is quite common for NEURON to be incorrectly installed from pip's
+point of view, you have to explicitly ask the BSB installation to install it:
+
+.. code-block:: bash
+
+    pip install bsb[neuron]
+
+After installation of the dependencies you will have to describe your cell models using
+`Arborize's <https://arborize.readthedocs.io>`_ ``NeuronModel`` template and import your
+Arborize cell models module into a ``MorphologyRepository``:
+
+.. code-block:: bash
+
+    $ bsb
+    > open mr morphologies.hdf5 --create
+    <repo 'morphologies.hdf5'> arborize my_models
+    numprocs=1
+    Importing MyCell1
+    Importing MyCell2
+    ...
+    <repo 'morphologies.hdf5'> exit
+
+This should allow you to use ``morphologies.hdf5`` and the morphologies contained within
+as the :guilabel:`morphology_repository` of the :guilabel:`output` node in your config:
+
+.. code-block:: json
+
+    {
+        "name": "Example config",
+        "output": {
+        "format": "bsb.output.HDF5Formatter",
+        "file": "my_network.hdf5",
+        "morphology_repository": "morphologies.hdf5"
+        }
+    }

setup.py

@@ -46,7 +46,7 @@
     },
     extras_require={
         "dev": ["sphinx", "furo", "pre-commit", "black==20.8b1"],
-        "NEURON": ["dbbs_models>=1.3.2", "nrn-patch>=3.0.0b0"],
-        "MPI": ["mpi4py"],
+        "neuron": ["NEURON>=7.8.1.1", "dbbs_models>=1.4.0", "nrn-patch>=3.0.0b0"],
+        "mpi": ["mpi4py"],
     },
 )