docs: New documentation

docs/connectivity/defining.rst

@@ -1,7 +1,12 @@
 ====================
-Defining connections
+Connectivity
 ====================
 
+The connection between cells is managed with ``ConnectivityStrategy`` objects. A strategy
+present all the rules to apply for the definition of connection among cells. In BSB is implemented
+a set of strategies ready to use (here is a :doc:`list </connectivity/connection-strategies>`), but it also possible to build a customised strategy.
+Once created the connectivity are stored in :class:`ConnectivitySets <.storage.interfaces.ConnectivitySet>`.
+
 Adding a connection type
 ========================
 

docs/getting-started/getting-started.rst

@@ -89,7 +89,7 @@ dimensions. See :doc:`/topology/intro` for more explanation on topology componen
 Cell types
 ----------
 
-The :class:`~.cell_types.CellType` is a definition of a cell population. During
+The :doc:`Cell Type </cells/intro>` is a definition of a cell population. During
 placement 3D positions, optionally rotations and morphologies or other properties will be
 created for them. In the simplest case you define a soma :guilabel:`radius` and
 :guilabel:`density` or fixed :guilabel:`count`:
@@ -119,12 +119,10 @@ Placement
     :lines: 19-24
 
 
-The ``placement`` blocks use the cell type indications to place cell types into
-partitions. You can use other :class:`PlacementStrategies
-<.placement.strategy.PlacementStrategy>` by setting the :guilabel:`strategy` attribute.
-The BSB offers some strategies out of the box, or you can implement your own. The
-:class:`~bsb.placement.random.RandomPlacement` places cells randomly in the assigned
-volume.
+The :doc:`placement </placement/intro>` blocks is charge to place cells in the partitions using the cell type indications.
+You can specify the strategy to use  by setting the :guilabel:`strategy` attribute.
+Here we use  the strategy :guilabel:`ParticlePlacement` that considers the cells as spheres and
+bumps them around as repelling particles until there is no overlap between them.
 
 Take another look at your network:
 
@@ -157,9 +155,8 @@ Connectivity
     :lines: 25-30
 
 
-The ``connectivity`` blocks specify connections between systems of cell types. They can
-create connections between single or multiple pre and postsynaptic cell types, and can
-produce one or many :class:`ConnectivitySets <.storage.interfaces.ConnectivitySet>`.
+The :doc:`connectivity </connectivity/defining>` blocks specify connections between systems of cell types. They can
+create connections between single or multiple cell types for both pre and post synaptic groups.
 
 Regenerate the network once more, now it will also contain your connections! With your
 cells and connections in place, you're ready to move to the :ref:`simulations` stage.

docs/getting-started/include_morphos.rst

@@ -83,10 +83,10 @@ change the name we can use a node with a :guilabel:`name` and :guilabel:`file`:
     :emphasize-lines: 3
 
 It is also possible to add a pipeline to perform transformations on the loaded
-morphology. Pipelines can be added by adding a :guilabel`pipeline` list to the morphology node.
+morphology. Pipelines can be added by adding a :guilabel:`pipeline` list to the morphology node.
 Each item in the list may either be a string reference to an importable function or a method of
 the :class:`~bsb.morphologies.Morphology` class. To pass parameters, use a node with the
-function reference placed in the guilabel:`func` attribute, and a :guilabel:`parameters` list.
+function reference placed in the :guilabel:`func` attribute, and a :guilabel:`parameters` list.
 Here is an example what that would look like:
 
 .. tab-set-code::
@@ -157,7 +157,7 @@ Morphology intersection
 -----------------------
 
 Now that we have assigned morphologies to our cell types, we can use morphology-based
-connection strategies such as :class:`~.connectivity.detailed.voxel_intersection.VoxelIntersection`:
+connection strategies such as :doc:`VoxelIntersection </connectivity/connection-strategies>`:
 
 .. tab-set-code::
 
@@ -176,7 +176,7 @@ connection strategies such as :class:`~.connectivity.detailed.voxel_intersection
 .. note::
 
   If there's multiple morphologies per cell type, they'll be assigned randomly, unless you
-  specify a :class:`~.placement.distributor.MorphologyDistributor`.
+  specify a :ref:`MorphologyDistributor <MorphologiesDistributors>`.
 
 
 Recap

docs/morphologies/intro.rst

@@ -461,6 +461,7 @@ Currently unspecified, up to the Storage and MorphologyRepository support to ret
 dictionary of available metadata from
 :meth:`~.storage.interfaces.MorphologyRepository.get_meta`.
 
+.. _MorphologiesDistributors:
 
 Morphology distributors
 -----------------------

docs/placement/intro.rst

@@ -0,0 +1,9 @@
+==========
+Placement
+==========
+This is the block that fills cells into partitions.
+The main object is the PlacementStrategy, a set of instructions for the definition of the positions of each cells in the partition volume.
+
+The BSB offers some strategies out of the box (here is a :doc:`list </placement/placement-strategies>`), or you can implement your own.
+
+The data is stored in :doc:`PlacementSets </placement/placement-set>` per cell type.

docs/placement/placement-strategies.rst

@@ -7,13 +7,46 @@ RandomPlacement
 
 *Class*: :class:`bsb.placement.RandomPlacement <.placement.random.RandomPlacement>`
 
+This class place cells in random postition without caring about overlaps. Here is an example with 10 cells.
+
+.. code-block:: json
+
+  {
+    "cell_types": {
+      "golgi_cell": {
+        "placement": {
+          "class": "bsb.placement.particle.RandomPlacement",
+          "layer": "granular_layer",
+          "count": 10
+          }
+      },
+    }
 
 ParallelArrayPlacement
 **********************
 
 *Class*: :class:`bsb.placement.ParallelArrayPlacement
 <.placement.arrays.ParallelArrayPlacement>`
 
+This class place cells in an aligned array, it create a lattice with fixed spacing and with the desired angle.
+It is necessary to specify ``spacing_x`` and ``angle`` attributes.
+
+.. code-block:: json
+
+  {
+    "cell_types": {
+      "golgi_cell": {
+        "placement": {
+          "class": "bsb.placement.arrays.ParallelArrayPlacement",
+          "layer": "granular_layer",
+          "count": 100,
+          "spacing_x": 10,
+          "angle": 0
+          }
+      },
+    }
+  }
+
 FixedPositions
 **************
 
@@ -37,3 +70,5 @@ This class places the cells in fixed positions specified in the attribute ``posi
       },
     }
   }
+
+

docs/placement/placement-toc.rst

@@ -2,5 +2,6 @@
    :maxdepth: 2
    :caption: Placement
 
+   intro
    placement-strategies
    placement-set

docs/topology/intro.rst

@@ -6,9 +6,9 @@ Layouts
 =======
 
 The topology module allows you to make abstract descriptions of the spatial layout of
-pieces of the region you are modelling. :class:`Partitions
-<.topology.partition.Partition>` define shapes such as layers, cubes, spheres, and meshes.
-:class:`Regions <.topology.region.Region>` put partitions together by arranging them
+pieces of the region you are modelling. :doc:`Partitions
+</topology/partitions>` define shapes such as layers, cubes, spheres, and meshes.
+:doc:`Regions </topology/regions>` put partitions together by arranging them
 hierarchically. The topology is formed as a tree of regions, that end downstream in a
 terminal set of partitions.
 
@@ -31,11 +31,11 @@ Example
   :figclass: only-dark
   :align: center
 
-The root :class:`Group <.topology.region.RegionGroup>` receives the network X, Y, and Z. A
+The root ``Group`` receives the network X, Y, and Z. A
 ``Group`` is an inert region and simply passes the network boundaries on to its children.
-The :class:`~.topology.partition.Voxels` loads its voxels, and positions them absolutely,
+The :ref:`Voxels <voxel-partition>` loads its voxels, and positions them absolutely,
 ignoring the network boundaries. The :class:`~.topology.region.Stack` passes the volume on
-to the :class:`Layers <.topology.partition.Layer>` who fill up the space and occupy their
+to the :ref:`Layers <layer-partition>` who fill up the space and occupy their
 thickness. They return their layout up to the parent ``Stack``, who in turn proposes
 translations to the layers in order to stack them on top of the other. The end result is
 stack beginning from the network starting corner, with 2 layers as large as the network,

docs/topology/partitions.rst

@@ -2,6 +2,83 @@
 Partitions
 ##########
 
+Partitions contain shape descriptions used for the spatial layout of the network.
+These descriptions can be represented as layers, meshes and voxelsets.
+In BSB are implemented two different kind of partitions: :ref:`layer  <layer-partition>` and :ref:`voxel based <voxel-partition>`.
+
+.. _layer-partition:
+
+======
+Layers
+======
+
+:class:`Layer partition <.topology.partition.Layer>` is a parallelepiped shaped volume.
+The size of a layer is defined by the network except for the height, therefore it is needed to
+specify the thickness of the layer with the ``thickness`` attribute.
+
+.. tab-set-code::
+
+    .. code-block:: json
+
+      {
+        "partitions": {
+          "my_layer_partition": {
+            "type": "layer",
+            "thickness": 25
+          }
+        }
+      }
+
+Cortical Model Use Case
+-----------------------
+
+
+Layers can be organized in a pile in order to separate the structure of your network according to the depth.
+:ref:`Stack <stack-region>` region is used to pile up your layers, for a three layer system it will be:
+
+.. tab-set-code::
+
+    .. code-block:: json
+
+        {
+            "name": "Starting example",
+            "storage": {
+            "engine": "hdf5",
+            "root": "network.hdf5"
+            },
+            "network": {
+                "x": 400.0,
+                "y": 600.0,
+                "z": 300.0
+            },
+            "regions": {
+                "brain_region": {
+                    "type": "stack",
+                    "children": ["base_layer","middle_layer","top_layer"]
+                }
+            },
+            "partitions": {
+                "base_layer": {
+                    "type": "layer",
+                    "thickness": 100,
+                    "stack_index": 0
+                },
+                "middle_layer": {
+                    "type": "layer",
+                    "thickness": 100,
+                    "stack_index": 1
+                },
+                "top_layer": {
+                    "type": "layer",
+                    "thickness": 100,
+                    "stack_index": 2
+                }
+            }
+        }
+
+
+
+
 .. _voxel-partition:
 
 ======

docs/topology/regions.rst

@@ -2,6 +2,14 @@
 Regions
 #######
 
+In BSB a regions is a hierarchical container of :doc:`partitions <topology/partitions>`
+used to manage different areas of the network.
+
+.. _stack-region:
+
 =======================
 List of builtin regions
 =======================
+
+BSB provide an implemented :class:`stack <.topology.regions.Stack>` type region that
+allow to create a pile of partitions.