Fix typography and rendering issues in documentation

Co-authored-by: C.A.P. Linssen <charl@turingbirds.com>

doc/concepts/decor.rst

@@ -26,10 +26,10 @@ The choice of region or locset is reflected in the two broad classes of dynamics
   * :ref:`Stimuli <cablecell-stimuli>`.
   * :ref:`Probes <cablecell-probes>`.
 
-Decorations are described by a **decor** object in Arbor.
-Provides facility for
-* setting properties defined over the whole cell
-* descriptions of dynamics applied to regions and locsets
+Decorations are described by a **decor** object in Arbor. It provides facilities for
+
+  * setting properties defined over the whole cell;
+  * descriptions of dynamics applied to regions and locsets.
 
 .. _cablecell-paint:
 
@@ -177,9 +177,9 @@ can't be overridden at cell or region level.
    :widths: 15, 10, 10
 
    **Ion**,     **name**, **Valence**
-   *Calcium*,   ca,       1
+   *Calcium*,   ca,       2
    *Potassium*,  k,       1
-   *Sodium*,    na,       2
+   *Sodium*,    na,       1
 
 Each ion species has the following properties:
 
@@ -198,7 +198,7 @@ If no reversal potential mechanism is specified for an ion species, the initial
 reversal potential values are maintained for the course of a simulation.
 Otherwise, the mechanism does the work.
 
-but it is subject to some strict restrictions.
+Reversal potential mechanisms are density mechanisms subject to some strict restrictions.
 Specifically, a reversal potential mechanism described in NMODL:
 
 * May not maintain any STATE variables.
@@ -215,7 +215,7 @@ and ionic state.
     mechanism only, that calculates reversal potentials according to concentrations
     that the other mechanisms use and modify.
 
-If a reversal potential mechanism that writes to multiple ions,
+If a reversal potential mechanism writes to multiple ions,
 it must be given for either no ions, or all of the ions it writes.
 
 Arbor's default catalogue includes a *nernst* reversal potential, which is

doc/concepts/labels.rst

@@ -575,7 +575,7 @@ Thingification
 
 When a region or locset expression is applied to a cell morphology, it is represented
 as a list of unbranched :term:`cables <cable>` or a set of :term:`locations <mlocation>` on the morphology.
-This process is called ``thingify`` in arbor, because it turns the abstract description
+This process is called ``thingify`` in Arbor, because it turns the abstract description
 of a :term:`region` or a :term:`locset` into an actual 'thing' when it is applied to a real morphology.
 
 .. note::
@@ -644,7 +644,7 @@ and a :ref:`decor <cablecell-decoration>`. The decorations can be painted or pla
 the regions or locsets defined in the label dictionary by referring to their labels.
 
 .. code-block:: python
-   :caption: Example of a lable dictionary in python:
+   :caption: Example of a label dictionary in python:
 
     arbor.label_dict({
       'soma': '(tag 1)',  # soma is every cable with tag 1 in the morphology.

doc/concepts/mechanisms.rst

@@ -47,7 +47,7 @@ Catalogues provide an interface for querying mechanism metadata, which includes
 
 Arbor provides a default catalogue of mechanisms as well as two other catalogues containing the sets of common mechanisms
 used by the `Allen Institute <https://alleninstitute.org/>`_ and the `Blue Brain Project <https://portal.bluebrain.epfl.ch/>`_.
-(Find the NMODL decsriptions of the `default mechanisms <https://github.com/arbor-sim/arbor/tree/master/mechanisms/default>`_,
+(Find the NMODL descriptions of the `default mechanisms <https://github.com/arbor-sim/arbor/tree/master/mechanisms/default>`_,
 the `Allen institute mechanisms <https://github.com/arbor-sim/arbor/tree/master/mechanisms/allen>`_ and
 the `BBP mechanisms <https://github.com/arbor-sim/arbor/tree/master/mechanisms/bbp>`_ at the provided links.)
 

doc/concepts/morphology.rst

@@ -53,7 +53,7 @@ proper definition for a morphology.
    **Field**,      **Type**,                           **Description**
    ``prox``,       :term:`mpoint`,   the centre and radius of the proximal end.
    ``dist``,       :term:`mpoint`,   the centre and radius of the distal end.
-   ``tag``,        integer,              ":term:`tag` meta-data, can be used to classify segments of the same kind (ex: soma, dendrite, but also arbitrary use-defined groups"
+   ``tag``,        integer,              ":term:`tag` meta-data, can be used to classify segments of the same kind (ex: soma, dendrite, but also arbitrary use-defined groups)"
 
 .. figure:: ../gen-images/term_segments.svg
   :width: 300
@@ -131,7 +131,7 @@ Segment trees
     and tools that iteratively construct cell morphologies (e.g. L-system generators, interactive cell-builders).
 
 Segment trees comprise a sequence of segments starting from
-at lease one :term:`root` segment, together with a parent-child adjacency relationship
+at least one :term:`root` segment, together with a parent-child adjacency relationship
 where a child segment is distal to its parent. Branches in the tree occur where a segment
 has more than one child. Furthermore, a segment can not have more than one parent.
 In this manner, neuron morphologies are modelled as a tree, where cables that
@@ -515,7 +515,7 @@ The simplest branching morphology is a cable that bifurcates into two branches,
 which we will call a *y-shaped cell*.
 In the example below, the first branch of the tree is a cable of length 10 μm with a
 a radius that tapers from 1 μm to 0.5 μm.
-The two child branches are attached to the end of the first branch, and taper from from 0.5 μ m
+The two child branches are attached to the end of the first branch, and taper from from 0.5 μm
 to 0.2 μm.
 
 Note that only the distal point is required to describe the child segments,
@@ -537,7 +537,7 @@ radius as the distal end of the parent.
 Example 4: Soma with branches
 """"""""""""""""""""""""""""""
 
-Now let's look at cell with a simple dendritic tree attached to a spherical soma.
+Now let's look at a cell with a simple dendritic tree attached to a spherical soma.
 The spherical soma of radius 3 μm is modelled with a cylinder with length and
 diameter equal to 6 μm, which has the same surface area as the sphere.
 
@@ -568,7 +568,7 @@ in the dendritic tree because the segments have parent child ordering and no for
     and no special treatment is given to the soma.
     There is no need to treat segments with different tags (e.g. tags that we might associate
     with soma, axon, basal dendrite and apical dendrite) when defining geometric primitives like
-    segments and branches, because they can later be referenced later using
+    segments and branches, because they can later be referenced using
     :ref:`region expressions <labels-expressions>`.
 
 Now we can attach another dendrite and an axon to the soma, to make a total of three cables
@@ -576,7 +576,7 @@ attached to the soma (two dendrites and an axon).
 The dendrites are attached to the distal end of the soma (segment 0), so they have the
 0 as their parent.
 The axon is attached to the proximal end of the soma, which is at the root of the tree,
-so it has :data:`mnpos` as its parent.
+so it has :py:data:`mnpos <arbor.mnpos>` as its parent.
 There are 7 branches generated from 10 segments, and soma segment is its own branch,
 because it has two children: the dendrites attached to its distal end.
 

doc/contrib/pr.rst

@@ -58,7 +58,7 @@ Each pull request is reviewed according to these guidelines:
    positive review.
 -  GitHub Actions CI must produce a favourable result on your PR.
 -  An Arbor team member will (squash) merge the PR with the PR change
-   summery as commit message.
+   summary as commit message.
 -  Consider using Gitpod to review larger PRs, see under checks on the Github PR page.
 
 .. _contribpr-merge:

doc/fileformat/asc.rst

@@ -46,7 +46,7 @@ Arbor supports description methods 1 and 2 following the `neuromporpho policies
 Currently multiple contours in method 3 are not supported, and if you need support make
 the request with an `issue <https://github.com/arbor-sim/arbor/issues>`_.
 
-In each case, the soma is modeled as a cylinder with diameter equal to it's length, centred
+In each case, the soma is modeled as a cylinder with diameter equal to its length, centred
 at the centre of the soma, and oriented along the y axis.
 
 For a **spherical** soma, the centre and diameter are that of the sphere. For

doc/fileformat/neuroml.rst

@@ -5,10 +5,10 @@ NeuroML2
 
 Arbor offers limited support for models described in `NeuroML version 2 <https://neuroml.org/neuromlv2>`_.
 This is not built by default (see :ref:`NeuroML support <install-neuroml>` for instructions on how
-to build arbor with NeuroML).
+to build Arbor with NeuroML).
 
 Once support is enabled, Arbor is able to parse and check the validity of morphologies described in NeuroML files,
-and present the encoded data to the user.  This is more than a simple a `segment tree`.
+and present the encoded data to the user.  This is more than a simple `segment tree`.
 
 NeuroML can encode in the same file multiple top-level morphologies, as well as cells:
 
@@ -34,7 +34,7 @@ Example
    </cell>
    </neuroml>
 
-The above NeuroML description defines 2 top-level morphologies ``m1`` and ``m2`` (empty); a cell ``c1`` that uses
+The above NeuroML description defines two top-level morphologies ``m1`` and ``m2`` (empty); a cell ``c1`` that uses
 morphology ``m1``; and a cell ``c2`` that uses an internally defined (empty) morphology ``m3``.
 
 Arbor can query the cells and morphologies using their ids and return all the associated morphological data for each.
@@ -46,4 +46,4 @@ API
 ^^^
 
 * :ref:`Python <pyneuroml>`
-* :ref:`C++ <cppneuroml>`
+* :ref:`C++ <cppneuroml>`
\ No newline at end of file

doc/fileformat/swc.rst

@@ -14,7 +14,7 @@ an `x,y,z` location in space, a radius, a tag and a parent id. Arbor parses thes
 then generates a morphology according to one of three possible interpretations.
 
 The SWC file format specifications are not very detailed, which has lead different simulators to interpret
-SWC files in different ways, especially when it comes to the soma. Arbor has its own an interpretation that
+SWC files in different ways, especially when it comes to the soma. Arbor has its own interpretation that
 is powerful and simple to understand at the same time. However, we have also developed functions that will
 interpret SWC files similarly to how the NEURON simulator would, and how the Allen Institute would.
 
@@ -32,7 +32,7 @@ is interpreted as a fork point in the morphology, and acts as the proximal point
 
 Arbor interpretation
 """"""""""""""""""""
-In addition to the previously listed checks, the arbor interpretation explicitly disallows SWC files where the soma is
+In addition to the previously listed checks, the Arbor interpretation explicitly disallows SWC files where the soma is
 described by a single sample. It constructs the soma from 2 or more samples, forming 1 or more segments. A *segment* is
 always constructed between a sample and its parent. This means that there are no gaps in the resulting morphology.
 
@@ -74,7 +74,7 @@ and all samples are translated in space towards the origin.
 NEURON interpretation
 """""""""""""""""""""
 The NEURON interpretation was obtained by experimenting with the ``Import3d_SWC_read`` function. We came up with the
-following set of rules that govern NEURON's SWC behavior and enforced them in arbor's NEURON-complaint SWC
+following set of rules that govern NEURON's SWC behavior and enforce them in Arbor's NEURON-complaint SWC
 interpreter:
 
 * SWC files must contain a soma sample and it must to be the first sample.
@@ -95,4 +95,4 @@ API
 """
 
 * :ref:`Python <pyswc>`
-* :ref:`C++ <cppswc>`
+* :ref:`C++ <cppswc>`
\ No newline at end of file

doc/math/model/appendix.tex

 %-----------------------------------
-\subsection{The conic frustrum}
+\subsection{The conic frustum}
 %-----------------------------------
-The derivation of the surface area of conic frustrum.
+The derivation of the surface area of conic frustum.
 The edge length $l$ is defined
 \begin{equation}
     l = \sqrt{(x_r - x_l)^2 + (a_r - a_l)^2} = \sqrt{\Delta x^2 + \Delta a^2}.
@@ -13,7 +13,7 @@ The lateral area of the surface is found by integrating along surface of rotatio
         &= 2\pi \int_{0}^{l} {a_{\ell} + \frac{s}{l}\left( a_r - a_\ell \right)} \deriv{s} \nonumber \\
         &= 2\pi \left[ a_{\ell}s + \frac{s^2}{2l}\left( a_r - a_\ell \right) \right]_0^l \nonumber \\
         &= \pi l \left( a_{\ell} + a_r \right) \nonumber \\
-        &= \pi \left( a_{\ell} + a_r \right) \sqrt{\Delta x^2 + \Delta a^2}. \label{eq:frustrum_area}
+        &= \pi \left( a_{\ell} + a_r \right) \sqrt{\Delta x^2 + \Delta a^2}. \label{eq:frustum_area}
 \end{align}
 
 There are two degenerate cases of interest. The first is the \emph{cylinder}, for which the radii at each end are euqal, i.e. $a_\ell = a_r = a$. In this case the lateral area of the surface is

doc/math/model/formulation.tex

@@ -93,7 +93,7 @@ The current, which is the conserved quantity in our conservation law, over the s
 This is derived from a thin film approximation to the cell membrane, whereby the membrane is treated as an infinitesimally thin interface between the intra and extra cellular regions.
 
 Note that some information is lost when going from a three-dimensional description of a neuron to a system of branching one-dimensional cable segments.
-If the cell is represented by cylinders or frustrums\footnote{a frustrum is a truncated cone, where the truncation plane is parallel to the base of the cone.}, the three-dimensional values for volume and surface area at branch points can't be retrieved from the one-dimensional description.
+If the cell is represented by cylinders or frustums\footnote{a frustum is a truncated cone, where the truncation plane is parallel to the base of the cone.}, the three-dimensional values for volume and surface area at branch points can't be retrieved from the one-dimensional description.
 
 \begin{figure}
     \begin{center}
@@ -201,14 +201,14 @@ The current terms are an average per unit area, therefore the total flux
 \end{equation}
 where $\sigma_i$ is the surface area the of the exterior of the cable segment, i.e. the surface corresponding to the cell membrane.
 
-Each cable segment is a conical frustrum, as illustrated in \fig{fig:segment}.
-The lateral surface area of a frustrum with height $\Delta x_i$ and radii of  is
+Each cable segment is a conical frustum, as illustrated in \fig{fig:segment}.
+The lateral surface area of a frustum with height $\Delta x_i$ and radii of  is
 The area of the external surface $\Gamma_{i}$ is
 \begin{equation}
     \sigma_i = \pi (a_{i,\ell} + a_{i,r}) \sqrt{\Delta x_i^2 + (a_{i,\ell} - a_{i,r})^2},
     \label{eq:cv_volume}
 \end{equation}
-where $a_{i,\ell}$ and $a_{i,r}$ are the radii of at the left and right end of the segment respectively (see~\eq{eq:frustrum_area} for derivation of this formula).
+where $a_{i,\ell}$ and $a_{i,r}$ are the radii of at the left and right end of the segment respectively (see~\eq{eq:frustum_area} for derivation of this formula).
 %-------------------------------------------------------------------------------
 \subsubsection{Putting it all together}
 %-------------------------------------------------------------------------------
@@ -228,7 +228,7 @@ is the area of the surface between two adjacent segments $i$ and $j$, and
     \sigma_{i}   = \pi(a_{i,\ell} + a_{i,r}) \sqrt{\Delta x_i^2 + (a_{i,\ell} - a_{i,r})^2},
     \label{eq:sigma_i}
 \end{equation}
-is the lateral area of the conical frustrum describing segment $i$.
+is the lateral area of the conical frustum describing segment $i$.
 
 %-------------------------------------------------------------------------------
 \subsubsection{Time Stepping}

doc/tutorial/index.rst

@@ -11,7 +11,7 @@ Tutorials
     installed independently from Arbor.
 
     In an interactive Python interpreter, you can use ``help()`` on any class or function to get its
-    documentation. (Try, ``help(arbor.simulation``, for example).
+    documentation. (Try, ``help(arbor.simulation)``, for example).
 
 .. Todo::
     Add more in-depth tutorial-like pages building up examples here.

doc/tutorial/network_ring.rst

@@ -65,7 +65,7 @@ These locations will form the endpoints of the connections between the cells.
 After we've created a basic :py:class:`arbor.decor`, step **(3)** places a synapse with an exponential decay (``'expsyn'``) is on the ``'synapse_site'``.
 Note that mechanisms can be initialized with their name; ``'expsyn'`` is short for ``arbor.mechanism('expsyn')``.
 
-Step **(4)** places a spike detector at the ``'root'``. :py:class:`spike_detectors <spike_detector>` will send spikes into an
+Step **(4)** places a spike detector at the ``'root'``. :py:class:`spike_detectors <arbor.spike_detector>` will send spikes into an
 :class:`arbor.connection`, whereas the :ref:`expsyn mechanism <mechanisms_builtins>` can receive spikes from an
 :class:`arbor.connection`.
 
@@ -195,8 +195,8 @@ In addition to having the timestamps of spikes, we want to extract the voltage a
 Step **(14)** sets the probes (step **10**) to measure at a certain schedule. This is sometimes described as
 attaching a :term:`sampler` to a :term:`probe`. :py:func:`arbor.simulation.sample` expects a :term:`probe id` and the
 desired schedule (here: a recording frequency of 10 kHz). Note that the probe id is a separate index from those of
-:term:`connection` endpoints; probe ids correspond to the index of the list produced by :py:func:`arbor.recipe.
-probes` on cell ``gid``.
+:term:`connection` endpoints; probe ids correspond to the index of the list produced by
+:py:func:`arbor.recipe.probes` on cell ``gid``.
 
 :py:func:`arbor.simulation.sample` returns a handle to the :term:`samples <sample>` that will be recorded. We store
 these handles for later use.

doc/tutorial/single_cell_detailed.rst

@@ -137,7 +137,7 @@ The label dictionary
 
 Next, we can define **region** and **location** expressions and give them labels.
 The regions and locations are defined using an Arbor-specific DSL, and the labels
-can be stored in a :class:`arbor.lable_dict`.
+can be stored in a :class:`arbor.label_dict`.
 
 .. Note::
 
@@ -157,7 +157,7 @@ defined as follows:
 
 .. code-block:: python
 
-    #Create a label dictionary
+    # Create a label dictionary
 
     labels = arbor.label_dict()
 
@@ -291,7 +291,7 @@ by the density mechanisms that we will be adding shortly.
 For both ions we set the default initial concentration and external concentration measures in mM;
 and we set the default initial reversal potential in mV. For the *na* ion, we additionally indicate
 the the progression on the reversal potential during the simulation will be dictated by the
-`nernst equation <https://en.wikipedia.org/wiki/Nernst_equation>`_.
+`Nernst equation <https://en.wikipedia.org/wiki/Nernst_equation>`_.
 
 It happens, however, that we want the temperature of the "custom" region defined in the label
 dictionary earlier to be colder, and the initial voltage of the "soma" region to be higher.
@@ -360,7 +360,7 @@ to be a single CV, and the rest of the morphology to be comprised of CVs with a
 The model
 *********
 
-We begin by constructing a :class:`arbor.single_cell_model` of the cell we just created.
+We begin by constructing an :class:`arbor.single_cell_model` of the cell we just created.
 
 .. code-block:: python
 
@@ -502,4 +502,4 @@ corresponding to each of the current clamps placed on the cell.
 
 The full code
 *************
-You can find the full code of the example at ``python/examples/single_cell_detailed.py``.
+You can find the full code of the example at ``python/examples/single_cell_detailed.py``.
\ No newline at end of file

doc/tutorial/single_cell_detailed_recipe.rst

@@ -194,7 +194,7 @@ Let's go through the recipe point by point.
 Step **(1)** creates a ``single_recipe`` class that inherits from :class:`arbor.recipe`. The base recipe
 implements all the methods defined above with default values except :meth:`arbor.recipe.num_cells`,
 :meth:`arbor.recipe.cell_kind` and :meth:`arbor.recipe.cell_description` which always have to be implemented
-by the user. The :meth:`arbor.recipe.gloabl_properties` also needs to be implemented for
+by the user. The :meth:`arbor.recipe.global_properties` also needs to be implemented for
 :class:`arbor.cell_kind.cable` cells. The inherited recipe can implement any number of additional methods and
 have any number of instance or class variables.
 
@@ -218,7 +218,7 @@ what we did in the :ref:`previous example <tutorialsinglecellswc-gprop>`. One la
    The mechanism catalogue needs to live in the recipe as an instance variable. Its lifetime needs to extend
    to the entire duration of the simulation.
 
-Step **(3)** overrides the :meth:`arbor.recipe.num_cells` method. It takes 0 arguments. We simply return 1,
+Step **(3)** overrides the :meth:`arbor.recipe.num_cells` method. It takes no arguments. We simply return 1,
 as we are only simulating one cell in this example.
 
 Step **(4)** overrides the :meth:`arbor.recipe.num_sources` method. It takes one argument: ``gid``.
@@ -284,7 +284,7 @@ previous section:
 The execution context
 *********************
 
-An :ref:`execution context <modelcontext>`_ describes the hardware resources on which the simulation will run.
+An :ref:`execution context <modelcontext>` describes the hardware resources on which the simulation will run.
 It contains the thread pool used to parallelise work on the local CPU, and optionally describes GPU resources
 and the MPI communicator for distributed simulations. In the previous
 examples, the :class:`arbor.single_cell_model` object created the execution context :class:`arbor.context`
@@ -354,7 +354,7 @@ Next, we instructed the simulation to sample ``probe_id`` at a frequency of 50 k
 The execution
 *************
 
-We can now run the simulation we just instantiated for a duration of 100ms with a time step of 0.025 ms.
+We can now run the simulation we just instantiated for a duration of 100 ms with a time step of 0.025 ms.
 
 .. code-block:: python
 
@@ -416,4 +416,4 @@ The following plot is generated. Identical to the plot of the previous example.
 The full code
 *************
 
-You can find the full code of the example at ``python/examples/single_cell_detailed_recipe.py``.
+You can find the full code of the example at ``python/examples/single_cell_detailed_recipe.py``.
\ No newline at end of file

doc/tutorial/single_cell_recipe.rst

@@ -114,8 +114,8 @@ and descriptions.
 
 Step **(4.5)** returns the cell description passed in on class initialisation. If we
 were modelling multiple cells of different kinds, we would need to make sure that the
-cell returned by :meth:arbor.recipe.cell_description has the same cell kind as
-returned by :meth:arbor.recipe.cell_kind for every :gen:gid.
+cell returned by :meth:`arbor.recipe.cell_description` has the same cell kind as
+returned by :meth:`arbor.recipe.cell_kind` for every :gen:`gid`.
 
 Step **(4.6)** returns the probes passed in at class initialisation.
 
@@ -131,10 +131,10 @@ The context and domain decomposition
 :class:`arbor.single_cell_model` does not only take care of the recipe, it also takes
 care of defining how the simulation will be run. When you create and use your own
 recipe, you'll need to do this manually, in the form of defining a execution context
-and a domain decomposition. Fortunately, the default constructors of :class:`arbor.
-context` and :class:`arbor.partition_load_balance` are sufficient for this model, and
-is what :class:`arbor.single_cell_model` does under the hood! We'll leave the details
-of this subject for another tutorial.
+and a domain decomposition. Fortunately, the default constructors of
+:class:`arbor.context` and :class:`arbor.partition_load_balance` are sufficient for
+this model, and is what :class:`arbor.single_cell_model` does under the hood! We'll
+leave the details of this subject for another tutorial.
 
 .. code-block:: python