fix: second round of feedback implementation.

README.md

@@ -8,7 +8,7 @@
 # BSB: A component framework for neural modelling
 
 Developed by the Department of Brain and Behavioral Sciences at the University of Pavia,
-the BSB is a component framework for neural modelling, which focusses on component
+the BSB is a component framework for neural modelling, which focuses on component
 declarations to piece together a model. The component declarations can be made in any
 supported configuration language, or using the library functions in Python. It offers
 parallel reconstruction and simulation of any network topology, placement and/or
@@ -29,7 +29,7 @@ pip install "bsb"
 ```
 
 Advanced users looking to control install an unconventional combination of plugins might
-be better of installing just this package, and the desired plugins:
+be better off installing just this package, and the desired plugins:
 
 ```
 pip install "bsb-core"
@@ -65,20 +65,28 @@ bsb new my_model --quickstart
 cd my_model
 ```
 
+This will create a `my_model` folder for you with some starter files. It should contain:
+
+- `network_configuration.yaml`: A configuration file in which your network will be described.
+- A `pyproject.toml` file: This file uses the TOML syntax to set configuration values for the BSB.
+- A `placement.py` and `connectome.py` files if you want to make your own components.
+
 ### Reconstructing a network
 
-You can use your project to create reconstructions of your model, generating cell positions
+Within your project folder, you can create reconstructions of your model, generating cell positions
 and connections:
 
 ```
 bsb compile
 ```
 
-This creates a network file.
+The `compile` command should produce a network file located in your project
+folder based on your configuration file.
 
 ### Simulating a network
 
-The default project currently contains no simulation config.
+The starter project contains no simulation configuration but the documentation provides tutorials
+for the neural simulators supported by the BSB.
 
 # Contributing
 

docs/cells/intro.rst

@@ -16,7 +16,7 @@ represented by **cell models**.
 .. rubric:: Basic configuration
 
 The :guilabel:`radius` and :guilabel:`density` are the 2 most basic :doc:`placement
-indications </placement/placement-indicators>`, they specify how large and dense the cells in the population generally are.
+indications </placement/placement-indicators>`: they specify how large and dense the cells in the population generally are.
 The :guilabel:`plotting` block allows you to specify formatting details.
 
 .. tab-set-code::
@@ -47,7 +47,7 @@ The :guilabel:`plotting` block allows you to specify formatting details.
 
 .. rubric:: Specifying spatial density
 
-You can set the spatial distribution for each cell type present in a
+You can set the spatial distribution for each cell type present in an
 :ref:`NrrdVoxels <voxel-partition>` partition.
 
 To do so, you should first attach your nrrd volumetric density file(s) to the partition with either
@@ -111,25 +111,25 @@ in the :guilabel:`cell_types` with :guilabel:`density_key`:
         )
 
         config.cell_types.add(
-        "first_cell_type",
-        spatial=dict(radius=10, density_key="first_cell_type_density")
-        plotting=dict(display_name="First Cell Type", color="pink",opacity="1.0")
+            "first_cell_type",
+            spatial=dict(radius=10, density_key="first_cell_type_density")
+            plotting=dict(display_name="First Cell Type", color="pink",opacity="1.0")
         )
         config.cell_types.add(
-        "second_cell_type",
-        spatial=dict(radius=10, density_key="second_cell_type_density")
-        plotting=dict(display_name="First Cell Type", color="#0000FF",opacity="0.5")
+            "second_cell_type",
+            spatial=dict(radius=10, density_key="second_cell_type_density")
+            plotting=dict(display_name="First Cell Type", color="#0000FF",opacity="0.5")
         )
 
-The nrrd files should contain voxel based volumetric density in unit of cells / voxel volume,
+The NRRD files should contain voxel based volumetric density in unit of cells / voxel volume,
 where the voxel volume is in cubic unit of :guilabel:`voxel_size`.
 i.e., if :guilabel:`voxel_size` is in µm then the density file is in cells/µm^3.
 
 .. rubric:: Specifying morphologies
 
 
-To associate a cell type with a specific morphology, add the desired morphology to the cells by referencing
-the corresponding name stored in the :doc:`morphology repository </morphologies/repository>`.
+The easiest way to associate a morphology to a cell type is by referencing the name it is stored under.
+There are more advanced ways as well, covered in our guide on :ref:`Morphology Selectors <morphology_selector>` .
 
 .. tab-set-code::
 

docs/cli/commands.rst

@@ -27,7 +27,7 @@ project settings.
 * ``quickstart``: Generates an exemplary project with basic config that can be compiled.
 * ``exists``: With this flag, it is not an error for the ``parent-folder`` to exist.
 * ``json``: With this flag, the configuration file will be written in the JSON format
-  instead of YAML format used by default.
+  instead of the default YAML format.
 
 .. _bsb_make_config:
 

docs/cli/intro.rst

@@ -4,7 +4,6 @@
 Introduction
 ############
 
-The command line interface is composed of a collection of pluggable commands.
 Open up your favorite terminal and enter the ``bsb --help`` command
 to verify you correctly installed the software.
 

docs/components/components.rst

@@ -11,8 +11,8 @@ If you want to read a step by step tutorial on how to make your own component, c
 :doc:`page </getting-started/guide_components>`
 
 For each component, the BSB provides interfaces, each with a set of functions that you must
-implement. By implementing these functions are present, the framework can seamlessly integrate
-your custom components.
+implement. By implementing these functions, the framework can seamlessly integrate your
+custom components.
 
 Here is how you do it (theoretically):
 

docs/getting-started/simulations/guide_nest.rst

@@ -326,7 +326,7 @@ You can now run your simulation:
 The results of the simulation will be stored in the ``"simulation-results"`` folder.
 
 .. note::
-    If you run the simulation with the command line interface, the name of the output nio file is randomized by BSB.
+    If you run the simulation with the command line interface, the name of the output nio file is randomized by the BSB.
 
 For more detailed information about simulation modules,
 please refer to the :doc:`simulation section </simulation/intro>`.

docs/getting-started/simulations/toc_point_neurons.rst

@@ -1,9 +1,9 @@
-Guides on Point neurons simulation
+Guides on Point-neurons simulation
 ==================================
 
 .. toctree::
   :maxdepth: 2
-  :caption: Point neuron simulations
+  :caption: Point-neuron simulations
 
   guide_nest
   analyze_spikes

docs/getting-started/top-level-guide.rst

@@ -20,7 +20,7 @@ A typical workflow of the BSB works as follows:
 1. The user provides a configuration that describes the network they want to reconstruct
    and simulate.
 
-   It is interpreted by BSB as a list of tasks to perform.
+   It is interpreted by the BSB as a series of tasks to perform.
 2. The BSB creates the topology of the network (i.e., its shape and size).
 3. The BSB places cells within the network, following a defined strategy.
 4. The BSB connects the aforementioned cells according to connectivity rules.
@@ -55,7 +55,7 @@ storage object full of neuroscience.
 
 To do so, the configuration leverages configurable objects to describe the underlying neural network,
 called **components**. Components define which methods and parameters should be used to reconstruct and
-simulate the network. The ones that you would probably employ the most are:
+simulate the network. The ones that you will probably employ the most are:
 
 * :guilabel:`Topology` defines the shape and volume of your network,
   (it is composed of :guilabel:`Regions` and :guilabel:`Partitions`),
@@ -78,9 +78,18 @@ Configuration
 =============
 
 The ``Configuration`` object is organized as a hierarchical tree.
-From the root, the main blocks branch off, consisting of nine main components: :guilabel:`network`,
-:guilabel:`storage`, :guilabel:`regions`, :guilabel:`partitions`, :guilabel:`morphologies`, :guilabel:`cell_types`,
-:guilabel:`placement`, :guilabel:`connectivity`, and :guilabel:`simulation`.
+From the root, the main blocks branch off, consisting of nine main components:
+
+* :guilabel:`network`
+* :guilabel:`storage`
+* :guilabel:`regions`
+* :guilabel:`partitions`
+* :guilabel:`morphologies`
+* :guilabel:`cell_types`
+* :guilabel:`placement`
+* :guilabel:`connectivity`
+* :guilabel:`simulation`
+
 These blocks contain nested sub-blocks that form the network.
 Additionally, there are two optional components: :guilabel:`after_placement` and :guilabel:`after_connectivity`,
 where users can define specific hooks to run within the workflow.
@@ -96,7 +105,7 @@ All these components will be described in more detail in the following sections.
 
 The configuration object contains only the description of the model, not its implementation (python code)
 nor its data (stored in the storage object).
-It can therefore be stored in a separate file (usually Json or Yaml) that can be easily interpreted by BSB.
+It can therefore be stored in a separate file (usually Json or Yaml) that can be easily interpreted by the BSB.
 
 What is next?
 =============

docs/morphologies/intro.rst

@@ -378,6 +378,8 @@ passed around in the framework as :class:`StoredMorphologies
 :class:`~.morphologies.Morphology` object from storage and a
 :meth:`~.storage.interfaces.StoredMorphology.get_meta` method to return the metadata.
 
+.. _morphology_selector:
+
 Morphology selectors
 --------------------