Docs markup improvements (#1483)

* Adapt CSS for the HTML5 transition in docutils 0.17
* Fix some reST markup errors
* Add meta-tag to enable indexation control at Google (current indexation appears at least a year old).

doc/concepts/decor.rst

@@ -28,8 +28,8 @@ The choice of region or locset is reflected in the two broad classes of dynamics
 
 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.
+* setting properties defined over the whole cell;
+* descriptions of dynamics applied to regions and locsets.
 
 .. _cablecell-paint:
 

doc/concepts/domdec.rst

@@ -6,8 +6,8 @@ Domain decomposition
 A *domain decomposition* describes the distribution of the model over the available computational resources.
 The description partitions the cells in the model as follows:
 
-    * group the cells into cell groups of the same :ref:`kind <modelcellkind>` of cell;
-    * assign each cell group to either a CPU core or GPU on a specific MPI rank.
+* group the cells into cell groups of the same :ref:`kind <modelcellkind>` of cell;
+* assign each cell group to either a CPU core or GPU on a specific MPI rank.
 
 The number of cells in each cell group depends on different factors, including the type of the cell, and whether the
 cell group will run on a CPU core or the GPU. The domain decomposition is solely responsible for describing the distribution

doc/concepts/morphology.rst

@@ -607,17 +607,7 @@ because it has two children: the dendrites attached to its distal end.
 Supported file formats
 ----------------------
 
-Arbor supports morphologies described using the SWC file format and the NeuroML file format.
-
-SWC
-~~~
-
-See :ref:`formatswc`
-
-NeuroML
-~~~~~~~
-
-See :ref:`formatneuroml`
+See the supported :ref:`file formats <format-overview>`.
 
 .. _morph-cv-policies:
 

doc/concepts/recipe.rst

@@ -6,16 +6,16 @@ Recipes
 An Arbor *recipe* is a description of a model. The recipe is queried during the model
 building phase to provide information about individual cells in the model, such as:
 
-  * The **number of cells** in the model.
-  * The **kind** of each cell.
-  * The **description** of each cell, e.g. with morphology, dynamics, synapses, detectors,
-    stimuli etc.
-  * The number of **spike targets** on each cell.
-  * The number of **spike sources** on each cell.
-  * The number of **gap junction sites** on each cell.
-  * Incoming **network connections** from other cells terminating on a cell.
-  * **Gap junction connections** on each cell.
-  * **Probes** on each cell.
+* The **number of cells** in the model.
+* The **kind** of each cell.
+* The **description** of each cell, e.g. with morphology, dynamics, synapses, detectors,
+  stimuli etc.
+* The number of **spike targets** on each cell.
+* The number of **spike sources** on each cell.
+* The number of **gap junction sites** on each cell.
+* Incoming **network connections** from other cells terminating on a cell.
+* **Gap junction connections** on each cell.
+* **Probes** on each cell.
 
 Recipes are structured to provide a consistent interface for describing each cell in the
 network using their global identifier (`gid`).
@@ -26,31 +26,31 @@ which helps make Arbor fast and easily distributable over many nodes.
 To better illustrate the content of a recipe, let's consider the following network of
 three cells:
 
--  | ``Cell 0``: Is a single soma, with ``hh`` (Hodgkin-huxley) dynamics. In the middle
-     of the soma, a spike detector is attached, it generates a spiking event when the
-     voltage goes above 10 mV. In the same spot on the soma, a current clamp is also
-     attached, with the intention of triggering some spikes. All of the preceding info:
-     the morphology, dynamics, spike detector and current clamp are what is referred to in
-     Arbor as the **description** of the cell.
-   | ``Cell 0`` should be modelled as a :ref:`cable cell<modelcablecell>`,
-     (because cable cells allow complex dynamics such as ``hh``). This is referred to as
-     the **kind** of the cell.
-   | It's quite expensive to build cable cells, so we don't want to do this too often.
-     But when the simulation is first set up, it needs to know how cells interact with
-     one another in order to distribute the simulation over the available computational
-     resources. This is why the number of **targets**, **sources** and **gap junction sites**
-     is needed separately from the cell description: with them, the simulation can tell
-     that ``cell 0`` has 1 **spike source** (the detector), 0 **spike targets**, and 0
-     **gap junction sites**, without having to build the cell.
--  | ``Cell 1``: Is a soma and a single dendrite, with ``passive`` dynamics everywhere.
-     It has a single synapse at the end of the dendrite and a gap junction site in the
-     middle of the soma. This is the **description** of the cell.
-     It's also a cable cell, which is its **cell kind**. It has 0 **spike sources**, 1
-     **spike target** (the synapse) and 1 **gap junction site**.
--  | ``Cell 2``: Is a soma and a single dendrite, with ``passive`` dynamics everywhere.
-     It has a gap junction site in the middle of the soma. This is the **description**
-     of the cell. It's also a cable cell, which is its **cell kind**. It has 0
-     **spike sources**, 0 **spike targets** and 1 **gap junction site**.
+- ``Cell 0``: Is a single soma, with ``hh`` (Hodgkin-huxley) dynamics. In the middle
+  of the soma, a spike detector is attached, it generates a spiking event when the
+  voltage goes above 10 mV. In the same spot on the soma, a current clamp is also
+  attached, with the intention of triggering some spikes. All of the preceding info:
+  the morphology, dynamics, spike detector and current clamp are what is referred to in
+  Arbor as the **description** of the cell.
+  ``Cell 0`` should be modelled as a :ref:`cable cell<modelcablecell>`,
+  (because cable cells allow complex dynamics such as ``hh``). This is referred to as
+  the **kind** of the cell.
+  It's quite expensive to build cable cells, so we don't want to do this too often.
+  But when the simulation is first set up, it needs to know how cells interact with
+  one another in order to distribute the simulation over the available computational
+  resources. This is why the number of **targets**, **sources** and **gap junction sites**
+  is needed separately from the cell description: with them, the simulation can tell
+  that ``cell 0`` has 1 **spike source** (the detector), 0 **spike targets**, and 0
+  **gap junction sites**, without having to build the cell.
+- ``Cell 1``: Is a soma and a single dendrite, with ``passive`` dynamics everywhere.
+  It has a single synapse at the end of the dendrite and a gap junction site in the
+  middle of the soma. This is the **description** of the cell.
+  It's also a cable cell, which is its **cell kind**. It has 0 **spike sources**, 1
+  **spike target** (the synapse) and 1 **gap junction site**.
+- ``Cell 2``: Is a soma and a single dendrite, with ``passive`` dynamics everywhere.
+  It has a gap junction site in the middle of the soma. This is the **description**
+  of the cell. It's also a cable cell, which is its **cell kind**. It has 0
+  **spike sources**, 0 **spike targets** and 1 **gap junction site**.
 
 The total **number of cells** in the model is 3. The **kind**, **description** and
 number of **spike sources**, **spike targets** and **gap junction sites** on each cell
@@ -89,10 +89,10 @@ Why recipes?
 
 The interface and design of Arbor recipes was motivated by the following aims:
 
-    * Building a simulation from a recipe description must be possible in a
-      distributed system efficiently with minimal communication.
-    * Minimising the amount of memory used in model building, making it
-      possible to build and run simulations in one run.
+* Building a simulation from a recipe description must be possible in a
+  distributed system efficiently with minimal communication.
+* Minimising the amount of memory used in model building, making it
+  possible to build and run simulations in one run.
 
 Recipe descriptions are cell-oriented, in order that the building phase can
 be efficiently distributed and that the model can be built independently of any
@@ -153,8 +153,8 @@ General best practices
     information only when requested.
     This has multiple benefits, including:
 
-        * thread safety;
-        * minimising the memory footprint of the recipe.
+    * thread safety;
+    * minimising the memory footprint of the recipe.
 
 .. topic:: Be reproducible
 

doc/concepts/simulation.rst

@@ -11,21 +11,21 @@ From recipe to simulation
 
 To build a simulation the following are needed:
 
-    * A :ref:`recipe <modelrecipe>` that describes the cells and connections in the model.
-    * A :ref:`domain decomposition <modeldomdec>` that describes the distribution of the
-      model over the local and distributed :ref:`hardware resources <modelhardware>`.
-    * An :ref:`execution context <modelcontext>` used to execute the simulation.
+* A :ref:`recipe <modelrecipe>` that describes the cells and connections in the model.
+* A :ref:`domain decomposition <modeldomdec>` that describes the distribution of the
+  model over the local and distributed :ref:`hardware resources <modelhardware>`.
+* An :ref:`execution context <modelcontext>` used to execute the simulation.
 
 Simulation execution and interaction
 ------------------------------------
 
 Simulations provide an interface for executing and interacting with the model:
 
-    * The simulation is executed/*run* by advancing the model state from the current simulation time to another
-      with maximum time step size.
-    * The model state can be *reset* to its initial state before the simulation was started.
-    * *Sampling* of the simulation state can be performed during execution with samplers and probes
-      and spike output with the total number of spikes generated since either construction or reset.
+* The simulation is executed/*run* by advancing the model state from the current simulation time to another
+  with maximum time step size.
+* The model state can be *reset* to its initial state before the simulation was started.
+* *Sampling* of the simulation state can be performed during execution with samplers and probes
+  and spike output with the total number of spikes generated since either construction or reset.
 
 API
 ---

doc/fileformat/asc.rst

 .. _formatasc:
 
-Neurlucida ASCII format
-~~~~~~~~~~~~~~~~~~~~~~~
+Neurolucida ASCII
+~~~~~~~~~~~~~~~~~
+
+.. csv-table::
+   :header: "Name", "File extension", "Read", "Write"
+
+   "Neurolucida", "``asc``", "✓", "✗"
 
 Arbor has support for reading cable cell morphologies described using the
-`Neurlucida ASCII file format <https://www.mbfbioscience.com/help/pdf/NL9.pdf>`_
-or ``.asc`` file format.
+`Neurolucida ASCII file format <https://www.mbfbioscience.com/help/pdf/NL9.pdf>`_.
 
 Because ASCII files contain both a morphology description and meta data, the
 loader returns both a morphology, and a label dictionary that describes regions

doc/fileformat/cable_cell.rst

 .. _formatcablecell:
 
-Arbor Cable Cell format (ACC)
-=============================
+Arbor Cable Cell
+================
+
+.. csv-table::
+   :header: "Name", "File extension", "Read", "Write"
+
+   "Arbor Cable Cell", "``acc``", "✓", "✓"
 
 We define an s-expression format for describing :ref:`cable cells <cablecell>`.
 Cable cells are constructed from three components: a :ref:`label dictionary <labels>`,

doc/fileformat/index.rst

+.. _format-overview:
+
+File formats
+============
+
+.. csv-table::
+   :header: "Name", "File extension", "Read", "Write"
+
+   "Arbor Cable Cell", "``acc``", "✓", "✓"
+   "SWC", "``swc``", "✓", "✗"
+   "NMODL", "``mod``", "✓", "✗"
+   "NeuroML2", "``nml``", "✓", "✗"
+   "Neurolucida", "``asc``", "✓", "✗"
+
+.. toctree::
+   :maxdepth: 2
+
+   cable_cell
+   asc
+   neuroml
+   nmodl
+   swc

doc/fileformat/neuroml.rst

@@ -3,6 +3,11 @@
 NeuroML2
 --------
 
+.. csv-table::
+   :header: "Name", "File extension", "Read", "Write"
+
+   "NeuroML2", "``nml``", "✓", "✗"
+
 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).

doc/fileformat/nmodl.rst

 .. _formatnmodl:
 
 NMODL
-======
+=====
+
+.. csv-table::
+   :header: "Name", "File extension", "Read", "Write"
+
+   "NMODL", "``mod``", "✓", "✗"
 
 *NMODL* is a `DSL <https://www.neuron.yale.edu/neuron/static/py_doc/modelspec/programmatic/mechanisms/nmodl.html>`_
 for describing ion channel and synapse dynamics that is used by NEURON,

doc/fileformat/swc.rst

@@ -3,6 +3,11 @@
 SWC
 ~~~
 
+.. csv-table::
+   :header: "Name", "File extension", "Read", "Write"
+
+   "SWC", "``swc``", "✓", "✗"
+
 Arbor supports reading morphologies described using the
 `SWC <http://www.neuronland.org/NLMorphologyConverter/MorphologyFormats/SWC/Spec.html>`_ file format.
 

doc/index.rst

@@ -162,3 +162,6 @@ A full list of our software attributions can be found `here <https://github.com/
    contrib/doc
    contrib/example
    contrib/test
+
+.. meta::
+   :google-site-verification: KbkW8d9MLsBFZz8Ry0tfcQRkHsgxzkECCahcyRSjWDo

doc/python/domdec.rst

@@ -163,18 +163,18 @@ Therefore, the following data structures are used to describe domain decompositi
 
     Return the indexes of a set of cells of the same kind that are grouped together in a cell group in an :class:`arbor.simulation`.
 
-        .. function:: group_description(kind, gids, backend)
+    .. function:: group_description(kind, gids, backend)
 
-            Construct a group description with parameters :attr:`kind`, :attr:`gids` and :attr:`backend`.
+        Construct a group description with parameters :attr:`kind`, :attr:`gids` and :attr:`backend`.
 
-        .. attribute:: kind
+    .. attribute:: kind
 
-            The kind of cell in the group.
+        The kind of cell in the group.
 
-        .. attribute:: gids
+    .. attribute:: gids
 
-            The list of gids of the cells in the cell group.
+        The list of gids of the cells in the cell group.
 
-        .. attribute:: backend
+    .. attribute:: backend
 
-            The hardware :class:`backend` on which the cell group will run.
+        The hardware :class:`backend` on which the cell group will run.

doc/python/hardware.rst

@@ -19,10 +19,10 @@ Helper functions for checking cmake or environment variables, as well as configu
 
     Returns a dictionary to check which options the Arbor library was configured with at compile time:
 
-      * ``ARB_MPI_ENABLED``
-      * ``ARB_WITH_MPI4PY``
-      * ``ARB_GPU_ENABLED``
-      * ``ARB_VERSION``
+    * ``ARB_MPI_ENABLED``
+    * ``ARB_WITH_MPI4PY``
+    * ``ARB_GPU_ENABLED``
+    * ``ARB_VERSION``
 
     .. container:: example-code
 

doc/python/simulation.rst

@@ -8,8 +8,8 @@ From recipe to simulation
 
 To build a simulation the following concepts are needed:
 
-    * an :py:class:`arbor.recipe` that describes the cells and connections in the model;
-    * an :py:class:`arbor.context` used to execute the simulation.
+* an :py:class:`arbor.recipe` that describes the cells and connections in the model;
+* an :py:class:`arbor.context` used to execute the simulation.
 
 The workflow to build a simulation is to first generate an
 :class:`arbor.domain_decomposition` based on the :py:class:`arbor.recipe` and :py:class:`arbor.context` describing the distribution of the model
@@ -50,16 +50,16 @@ over the local and distributed hardware resources (see :ref:`pydomdec`). Then, t
 
     The **constructor** takes
 
-        * an :py:class:`arbor.recipe` that describes the model;
-        * an :py:class:`arbor.domain_decomposition` that describes how the cells in the model are assigned to hardware resources;
-        * an :py:class:`arbor.context` which is used to execute the simulation.
+    * an :py:class:`arbor.recipe` that describes the model;
+    * an :py:class:`arbor.domain_decomposition` that describes how the cells in the model are assigned to hardware resources;
+    * an :py:class:`arbor.context` which is used to execute the simulation.
 
     Simulations provide an interface for executing and interacting with the model:
 
-        * Specify what data (spikes, probe results) to record.
-        * **Advance the model state** by running the simulation up to some time point.
-        * Retrieve recorded data.
-        * Reset simulator state back to initial conditions.
+    * Specify what data (spikes, probe results) to record.
+    * **Advance the model state** by running the simulation up to some time point.
+    * Retrieve recorded data.
+    * Reset simulator state back to initial conditions.
 
     **Constructor:**
 
@@ -286,60 +286,61 @@ Definitions
 Procedure
 *********
 
-    There are three parts to the process of recording cell data over a simulation.
+There are three parts to the process of recording cell data over a simulation.
 
-    1. Describing what to measure.
+1. Describing what to measure.
 
-       The recipe object must provide a method :py:func:`recipe.get_probes` that returns a list of
-       probe addresses for the cell with a given ``gid``. The kth element of the list corresponds
-       to the :term:`probe id` ``(gid, k)``.
+   The recipe object must provide a method :py:func:`recipe.get_probes` that returns a list of
+   probe addresses for the cell with a given ``gid``. The kth element of the list corresponds
+   to the :term:`probe id` ``(gid, k)``.
 
-       Each probe address is an opaque object describing what to measure and where, and each cell kind
-       will have its own set of functions for generating valid address specifications. Possible cable
-       cell probes are described in the cable cell documentation: :ref:`pycablecell-probesample`.
+   Each probe address is an opaque object describing what to measure and where, and each cell kind
+   will have its own set of functions for generating valid address specifications. Possible cable
+   cell probes are described in the cable cell documentation: :ref:`pycablecell-probesample`.
 
-    2. Instructing the simulator to record data.
+2. Instructing the simulator to record data.
 
-       Recording is set up with the method :py:func:`simulation.sample`
-       as described above. It returns a handle that is used to retrieve the recorded data after
-       simulation.
+   Recording is set up with the method :py:func:`simulation.sample`
+   as described above. It returns a handle that is used to retrieve the recorded data after
+   simulation.
 
-    3. Retrieve recorded data.
+3. Retrieve recorded data.
 
-       The method :py:func:`simulation.samples` takes a handle and returns the recorded data as a list,
-       with one entry for each probe associated with the :term:`probe id` that was used in step 2 above. Each
-       entry will be a tuple ``(data, meta)`` where ``meta`` is the metadata associated with the
-       probe, and ``data`` contains all the data sampled on that probe over the course of the
-       simulation.
+   The method :py:func:`simulation.samples` takes a handle and returns the recorded data as a list,
+   with one entry for each probe associated with the :term:`probe id` that was used in step 2 above. Each
+   entry will be a tuple ``(data, meta)`` where ``meta`` is the metadata associated with the
+   probe, and ``data`` contains all the data sampled on that probe over the course of the
+   simulation.
 
-       The contents of ``data`` will depend upon the specifics of the probe, but note:
+   The contents of ``data`` will depend upon the specifics of the probe, but note:
 
-       i. The object type and structure of ``data`` is fully determined by the metadata.
+   i. The object type and structure of ``data`` is fully determined by the metadata.
 
-       ii. All currently implemented probes return data that is a NumPy array, with one
-           row per sample, first column being sample time, and the remaining columns containing
-           the corresponding data.
+   ii. All currently implemented probes return data that is a NumPy array, with one
+       row per sample, first column being sample time, and the remaining columns containing
+       the corresponding data.
 
-.. container:: example-code
+Example
+*******
 
-    .. code-block:: python
+.. code-block:: python
 
-        import arbor
+    import arbor
 
-        # [... define recipe, decomposition, context ... ]
-        # Initialize simulation:
+    # [... define recipe, decomposition, context ... ]
+    # Initialize simulation:
 
-        sim = arbor.simulation(recipe, decomp, context)
+    sim = arbor.simulation(recipe, decomp, context)
 
-        # Sample probe id (0, 0) (first probe id on cell 0) every 0.1 ms with exact sample timing:
+    # Sample probe id (0, 0) (first probe id on cell 0) every 0.1 ms with exact sample timing:
 
-        handle = sim.sample((0, 0), arbor.regular_schedule(0.1), arbor.sampling_policy.exact)
+    handle = sim.sample((0, 0), arbor.regular_schedule(0.1), arbor.sampling_policy.exact)
 
-        # Run simulation and retrieve sample data from the first probe associated with the handle.
+    # Run simulation and retrieve sample data from the first probe associated with the handle.
 
-        sim.run(tfinal=3, dt=0.1)
-        data, meta = sim.samples(handle)[0]
-        print(data)
+    sim.run(tfinal=3, dt=0.1)
+    data, meta = sim.samples(handle)[0]
+    print(data)
 
 >>> [[  0.         -50.        ]
 >>>  [  0.1        -55.14412111]

doc/python/single_cell_model.rst

@@ -14,39 +14,39 @@ Single cell model
    cable cells.
    The simulation can not be distributed over several machines.
 
-    .. method:: single_cell_model(cable_cell)
+   .. method:: single_cell_model(cable_cell)
 
-       Construct a :class:`single_cell_model` from a :class:`cable_cell`
+      Construct a :class:`single_cell_model` from a :class:`cable_cell`
 
-    .. method:: run(tfinal, dt)
+   .. method:: run(tfinal, dt)
 
-       Run the model from time t= ``0`` to t= ``tflinal`` with a dt= ``dt``.
+      Run the model from time t= ``0`` to t= ``tflinal`` with a dt= ``dt``.
 
-    .. method:: probe(what, where, frequency)
+   .. method:: probe(what, where, frequency)
 
-       Sample a variable on the cell:
+      Sample a variable on the cell:
 
-       :param what: Name of the variable to record (currently only 'voltage').
-       :param where: :class:`location` at which to sample the variable.
-       :param frequency: The frequency at which to sample [kHz].
+      :param what: Name of the variable to record (currently only 'voltage').
+      :param where: :class:`location` at which to sample the variable.
+      :param frequency: The frequency at which to sample [kHz].
 
-    .. method:: spikes()
+   .. method:: spikes()
 
-       Returns a list spike times [ms] after a call to :class:`single_cell_model.run`.
+      Returns a list spike times [ms] after a call to :class:`single_cell_model.run`.
 
-    .. method:: traces()
+   .. method:: traces()
 
-       Returns a list of :class:`trace` after a call to  :class:`single_cell_model.run`.
-       Each element in the list holds the trace of one of the probes added via
-       :class:`single_cell_model.probe`.
+      Returns a list of :class:`trace` after a call to  :class:`single_cell_model.run`.
+      Each element in the list holds the trace of one of the probes added via
+      :class:`single_cell_model.probe`.
 
-    .. attribute:: properties
+   .. attribute:: properties
 
-       The :class:`cable_global_properties` of the model.
+      The :class:`cable_global_properties` of the model.
 
-    .. attribute:: catalogue
+   .. attribute:: catalogue
 
-       The :class:`mechanism_catalogue` of the model.
+      The :class:`mechanism_catalogue` of the model.
 
 .. py:class:: trace
 

doc/requirements.txt

 sphinx>=2.4.0
 svgwrite
+docutils >= 0.17