fix: Implement feedback on new docs (#905)

* fix: Take review feedback into account

* fix: add GHA test in case of no version bump

* fix: second round of feedback implementation.

* fix: third round on feedback implementation

* fix: drop dependency to colour

.github/workflows/main.yml

@@ -17,7 +17,7 @@ jobs:
   api:
     uses: ./.github/workflows/api.yml
 
-  tag_release:
+  bump:
     needs: [isort, black, build, docs, api]
     runs-on: ubuntu-latest
     outputs:
@@ -44,35 +44,55 @@ jobs:
         with:
           token: ${{ steps.app-token.outputs.token }}
           branch: main
+          noVersionBumpBehavior: warn
+
+  tag_release:
+    needs: [ bump ]
+    # Skip job in case no version bump is required
+    # in this case the variable tag will not be set by semver
+    if: ${{ needs.bump.outputs.tag != ''}}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create Github token
+        uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          app-id: ${{ vars.DBBS_APP_ID }}
+          private-key: ${{ secrets.DBBS_APP_PRIVATE_KEY }}
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ steps.app-token.outputs.token }}
 
       - name: Set up Python 3.11
-        uses: actions/setup-python@v1
+        uses: actions/setup-python@v5
         with:
           python-version: 3.11
 
       - name: Bump version in Python project
         run: |
           pip install --upgrade pip bump-my-version
-          oldv="${{ steps.semver.outputs.current }}"
-          newv="${{steps.semver.outputs.next}}"
+          oldv="${{ needs.bump.outputs.old_tag }}"
+          newv="${{needs.bump.outputs.tag}}"
           # Bump the version, dropping the leading `v` with `${x:1}`
           bump-my-version replace --current-version=${oldv:1} --new-version=${newv:1} pyproject.toml
 
       - name: Commit & Push version change
-        uses: stefanzweifel/git-auto-commit-action@v4
+        uses: stefanzweifel/git-auto-commit-action@v5
         with:
           branch: main
-          commit_message: 'docs: bump version: ${{ steps.semver.outputs.current }} → ${{ steps.semver.outputs.next }} [skip ci]'
+          commit_message: 'docs: bump version: ${{ needs.bump.outputs.old_tag }} → ${{ needs.bump.outputs.tag }} [skip ci]'
 
       - name: Create tag
         uses: rickstaa/action-create-tag@v1
         with:
-          tag: ${{ steps.semver.outputs.next }}
+          tag: ${{ needs.bump.outputs.tag }}
           github_token: ${{ steps.app-token.outputs.token }}
 
   release:
     runs-on: ubuntu-latest
-    needs: tag_release
+    needs: [bump, tag_release]
 
     steps:
       - name: Create Github token
@@ -97,22 +117,22 @@ jobs:
         uses: requarks/changelog-action@v1
         with:
           token: ${{ steps.app-token.outputs.token }}
-          fromTag: ${{ needs.tag_release.outputs.tag }}
-          toTag: ${{ needs.tag_release.outputs.old_tag }}
+          fromTag: ${{ needs.bump.outputs.tag }}
+          toTag: ${{ needs.bump.outputs.old_tag }}
 
       - name: Create Release
         uses: ncipollo/[email protected]
         with:
           allowUpdates: true
           draft: false
           makeLatest: true
-          tag: ${{ needs.tag_release.outputs.tag }}
-          name: ${{ needs.tag_release.outputs.tag }}
+          tag: ${{ needs.bump.outputs.tag }}
+          name: ${{ needs.bump.outputs.tag }}
           body: ${{ steps.changelog.outputs.changes }}
           token: ${{ steps.app-token.outputs.token }}
 
       - name: Commit CHANGELOG.md
-        uses: stefanzweifel/git-auto-commit-action@v4
+        uses: stefanzweifel/git-auto-commit-action@v5
         with:
           branch: main
           commit_message: 'docs: update CHANGELOG.md for ${{ github.ref_name }} [skip ci]'

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 -p
+bsb compile
 ```
 
-This creates a [network file](bsb.readthedocs.io/getting-started/networks.html) and plots the network.
+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
 

bsb/cli/commands/_commands.py

@@ -207,7 +207,7 @@ def handler(self, context):
             for name, sim in extra_simulations.items():
                 if name not in network.simulations and name == sim_name:
                     network.simulations[sim_name] = sim
-        root = pathlib.Path(getattr(context.arguments, "output_folder", "./"))
+        root = pathlib.Path(getattr(context.arguments, "output-folder", "./"))
         if not root.is_dir() or not os.access(root, os.W_OK):
             return report(
                 f"Output provided '{root.absolute()}' is not an existing directory with write access.",
@@ -231,7 +231,7 @@ def get_options(self):
     def add_parser_arguments(self, parser):
         parser.add_argument("network")
         parser.add_argument("simulation")
-        parser.add_argument("-o", "--output_folder")
+        parser.add_argument("-o", "--output-folder")
 
 
 class CacheCommand(BaseCommand, name="cache"):  # pragma: nocover

bsb/config/_distributions.py

@@ -29,7 +29,7 @@ class Distribution:
     )
     """Name of the scipy.stats distribution function"""
     parameters: dict[str, typing.Any] = config.catch_all(type=types.any_())
-    """parameters to pass to the distribution"""
+    """Parameters to pass to the distribution"""
 
     def __init__(self, **kwargs):
         if self.distribution == "constant":

bsb/connectivity/strategy.py

@@ -168,7 +168,7 @@ def connect(self, presyn_collection, postsyn_collection):
         Central method of each connection strategy. Given a pair of
         ``HemitypeCollection`` (one for each connection side), should connect
         cell population using the scaffold's (available as ``self.scaffold``)
-        :func:`~bsb.core.Scaffold.connect_cells` method.
+        :meth:`bsb.core.Scaffold.connect_cells` method.
 
         :param bsb.connectivity.strategy.HemitypeCollection presyn_collection:
           presynaptic filtered cell population.

bsb/core.py

@@ -795,7 +795,7 @@ def create_job_pool(self, fail_fast=None, quiet=False):
         )
         try:
             # Check whether stdout is a TTY, and that it is larger than 0x0
-            # (e.g. MPI sets it to 0x0 unless a xterm is emulated.
+            # (e.g. MPI sets it to 0x0 unless an xterm is emulated).
             tty = os.isatty(sys.stdout.fileno()) and sum(os.get_terminal_size())
         except Exception:
             tty = False

bsb/mixins.py

@@ -27,11 +27,10 @@ def _all_chunks(iter_):
 
 
 def _queue_connectivity(self, pool: "JobPool"):
-    """Get the queued jobs of all the strategies we depend on.
+    """
+    Get the queued jobs of all the strategies we depend on.
 
-    Parameters
-    ----------
-    param pool : pool where the jobs will be queued
+    param pool: pool where the jobs will be queued
     type pool: bsb.services.pool.JobPool
     """
     deps = set(_gutil.ichain(pool.get_submissions_of(strat) for strat in self.get_deps()))

docs/cells/intro.rst

@@ -2,21 +2,18 @@
 Cell Types
 ==========
 
-A cell types contains information about cell populations. There are 2 categories: cells,
-and entities. A cell has a position, while an entity does not. Cells can also have
-morphologies and orientations associated with them. On top of that, both cells and
-entities support additional arbitrary properties.
-
-A cell type is an abstract description of the population. During placement, the concrete
-data is generated in the form of a :doc:`PlacementSet </placement/placement-set>`. These can
-then be connected together into :class:`ConnectivitySets
+A cell type is an abstract description of a cell population. Cell populations are
+placed within `Partitions` according to :doc:`placement indications </placement/placement-indicators>`.
+You can also attach morphologies and orientations to them.
+During placement, the cell positions are generated in the form of a :doc:`PlacementSet </placement/placement-set>`.
+These can then be connected together into :class:`ConnectivitySets
 <.storage.interfaces.ConnectivitySet>`. Furthermore, during simulation, cell types are
 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.
+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.
 The :guilabel:`plotting` block allows you to specify formatting details.
 
 .. tab-set-code::
@@ -47,10 +44,12 @@ 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
-:ref:`NrrdVoxels <bsb:voxel-partition>` partition.
+In the previous example, we were setting the number of cells to place within each partition
+based on a single density value. Let's imagine now that you want to describe the spatial
+distribution of the cell type spatial density for each voxel within your partition.
+This can be achieved with the :ref:`NrrdVoxels <voxel-partition>` partition.
 
-To do so, you should first attach your nrrd volumetric density file(s) to the partition with either
+To do so, you should first attach your NRRD volumetric density file(s) to the partition with either
 the :guilabel:`source` or :guilabel:`sources` blocks.
 Then, label the file(s) with the :guilabel:`keys` list block and refer to the :guilabel:`keys`
 in the :guilabel:`cell_types` with :guilabel:`density_key`:
@@ -111,25 +110,26 @@ 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.
+This implementation corresponds to an atlas-based reconstruction and you can find an example of
+a BSB configuration using the Allen Atlas in :doc:`this section </examples/atlas/atlas_placement>` .
 
 .. 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::
 
@@ -162,4 +162,5 @@ the corresponding name stored in the :doc:`morphology repository </morphologies/
         )
 
 In this case we add two different morphologies labels:
-:guilabel:`cell_B_2` add the morphology with this name, :guilabel:`cells_A_*` add all the stored morphologies with name starting with ``cells_A_`` prefix.
+:guilabel:`cell_B_2` add the morphology with this name, :guilabel:`cells_A_*` add all the stored morphologies with name starting with ``cells_A_`` prefix.
+You can also apply transformation to your cell morphologies as discussed in :ref:`this section<transform>`.

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

@@ -10,10 +10,9 @@ out of the box components for basic operations, but often you'll need to write y
 If you want to read a step by step tutorial on how to make your own component, check this
 :doc:`page </getting-started/guide_components>`
 
-For each component, BSB provides interfaces, each with a set of functions that you must
-implement. If these functions are present, the framework knows how to use your class.
-
-Hence, the framework allows you to plug in user code pretty much anywhere. Neat.
+For each component, the BSB provides interfaces, each with a set of functions that you must
+implement. By implementing these functions, the framework can seamlessly integrate your
+custom components into a BSB workflow. Neat!
 
 Here is how you do it (theoretically):
 

docs/conf.py

@@ -79,7 +79,6 @@
     "mpi4py": ("https://mpi4py.readthedocs.io/en/stable/", None),
     "arbor": ("https://docs.arbor-sim.org/en/latest/", None),
     "neo": ("https://neo.readthedocs.io/en/latest/", None),
-    "bsb": ("https://bsb.readthedocs.io/en/latest", None),
 }
 
 # Add any paths that contain templates here, relative to this directory.

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-neuron simulations
 ==================================
 
 .. toctree::
   :maxdepth: 2
-  :caption: Point neuron simulations
+  :caption: Point-neuron simulations
 
   guide_nest
   analyze_spikes