Rearranged the documentation source to have nicer URLs on the website. (#1188)

.readthedocs.yml

@@ -3,12 +3,17 @@
 
 version: 2
 
+submodules:
+  include: all
+  recursive: true
+
 sphinx:
   configuration: doc/conf.py
 
-formats: all
+formats: []
 
 python:
   version: 3.7
+  system_packages: true
   install:
-    - requirements: doc/requirements.txt
+    - requirements: doc/requirements.txt
\ No newline at end of file

doc/co_overview.rst → doc/concepts/index.rst

 .. _modelintro:
 
-Overview
-=========
+Concepts
+====================
+
+To understand how to use Arbor, it is helpful if you understand some of its concepts.
+
 Arbor's design aims to enable scalability through abstraction.
 
 To achieve this, Arbor makes a distinction between the **description** of a model, and the
@@ -21,3 +24,18 @@ A cell represents the smallest unit of computation and forms the smallest unit o
 :ref:`modelsimulation` manage the instantiation of the model and the scheduling of spike exchange as well as the integration for each cell group. A cell group represents a collection of cells of the same type computed together on the GPU or CPU. The partitioning into cell groups is provided by :ref:`modeldomdec` which describes the distribution of the model over the locally available computational resources.
 
 In order to visualize the result of detected spikes a spike recorder can be used and to analyse Arbor's performance a meter manager is available.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Arbor concepts:
+
+   recipe
+   cell
+   cable_cell
+   morphology
+   labels
+   mechanisms
+   interconnectivity
+   hardware
+   domdec
+   simulation

doc/co_interconnectivity.rst → doc/concepts/interconnectivity.rst

 .. _co_interconnectivity:
 
 Interconnectivity
-#################
+=================
 
 Networks can be regarded as a sort of graph, where the nodes are cells and the edges
 describe the communications between them. In Arbor, two sorts of edges are modelled: a
@@ -16,7 +16,7 @@ Connection sites and gap junction sites are defined on locations on cells (more
 .. _modelconnections:
 
 Connections
-===========
+-----------
 
 Connections implement chemical synapses between **source** and **target** cells and are characterized by having a transmission delay.
 
@@ -28,7 +28,7 @@ Connections in Arbor are defined in two steps:
 .. _modelgapjunctions:
 
 Gap junctions
-=============
+-------------
 
 Gap junctions represent electrical synapses where transmission between cells is bidirectional and direct.
 They are modeled as a conductance between two **gap junction sites** on two cells.

doc/co_labels.rst → doc/concepts/labels.rst

@@ -20,7 +20,7 @@ descriptions. It has a soma, dendritic tree and an axon with a hillock:
 
 .. _labels-morph-fig:
 
-.. figure:: gen-images/label_morph.svg
+.. figure:: ../gen-images/label_morph.svg
   :width: 800
   :align: left
 
@@ -58,7 +58,7 @@ which may contain multiple instances of the same location, for example:
 * The locations of inhibitory synapses.
 * The tips of the dendritic tree.
 
-.. figure:: gen-images/locset_label_examples.svg
+.. figure:: ../gen-images/locset_label_examples.svg
   :width: 800
   :align: center
 
@@ -91,7 +91,7 @@ the region of cables that have radius less than 0.5 μm
 
 .. _labels-region-examples:
 
-.. figure:: gen-images/region_label_examples.svg
+.. figure:: ../gen-images/region_label_examples.svg
   :width: 800
   :align: center
 
@@ -204,7 +204,7 @@ dendritic tree where the radius first is less than or equal to 0.2 μm.
 Locset expressions
 ~~~~~~~~~~~~~~~~~~~~~
 
-.. figure:: gen-images/label_branch.svg
+.. figure:: ../gen-images/label_branch.svg
   :width: 800
   :align: center
 
@@ -217,7 +217,7 @@ Locset expressions
 
     Equivalent to ``(location 0 0)``.
 
-    .. figure:: gen-images/root_label.svg
+    .. figure:: ../gen-images/root_label.svg
       :width: 300
       :align: center
 
@@ -230,7 +230,7 @@ Locset expressions
     of branch length, so for example, on a branch of length 100 μm ``pos=0.2``
     corresponds to 20 μm from the proximal end, or 80 μm from the distal end.
 
-    .. figure:: gen-images/location_label.svg
+    .. figure:: ../gen-images/location_label.svg
       :width: 300
       :align: center
 
@@ -241,7 +241,7 @@ Locset expressions
     The location of terminal points, which are the most distal locations on the morphology.
     These will typically correspond to the tips, or end points, of dendrites and axons.
 
-    .. figure:: gen-images/term_label.svg
+    .. figure:: ../gen-images/term_label.svg
       :width: 300
       :align: center
 
@@ -249,7 +249,7 @@ Locset expressions
 
 .. label:: (uniform reg:region first:int last:int seed:int)
 
-    .. figure:: gen-images/uniform_label.svg
+    .. figure:: ../gen-images/uniform_label.svg
       :width: 600
       :align: center
 
@@ -261,7 +261,7 @@ Locset expressions
 
     The set of locations ``{(location b pos) | 0 ≤ b < nbranch-1}``.
 
-    .. figure:: gen-images/on_branches_label.svg
+    .. figure:: ../gen-images/on_branches_label.svg
       :width: 300
       :align: center
 
@@ -272,7 +272,7 @@ Locset expressions
     The set of the most distal locations of a region.
     These are defined as the locations for which there are no other locations more distal in the region.
 
-    .. figure:: gen-images/distal_label.svg
+    .. figure:: ../gen-images/distal_label.svg
       :width: 600
       :align: center
 
@@ -284,7 +284,7 @@ Locset expressions
     The set of the most proximal locations of a region.
     These are defined as the locations for which there are no other locations more proximal in the region.
 
-    .. figure:: gen-images/proximal_label.svg
+    .. figure:: ../gen-images/proximal_label.svg
       :width: 600
       :align: center
 
@@ -300,7 +300,7 @@ Locset expressions
 
     The set of locations in the locset ``loc`` that are in the region ``reg``.
 
-    .. figure:: gen-images/restrict_label.svg
+    .. figure:: ../gen-images/restrict_label.svg
       :width: 600
       :align: center
 
@@ -359,7 +359,7 @@ Region expressions
 
     All branches in the morphology.
 
-    .. figure:: gen-images/nil_all_label.svg
+    .. figure:: ../gen-images/nil_all_label.svg
       :width: 600
       :align: center
 
@@ -369,7 +369,7 @@ Region expressions
 
     All of the segments with :ref:`tag <morph-tag-definition>` ``tag_id``.
 
-    .. figure:: gen-images/tag_label.svg
+    .. figure:: ../gen-images/tag_label.svg
       :width: 900
       :align: center
 
@@ -380,7 +380,7 @@ Region expressions
 
     Refer to a branch by its id.
 
-    .. figure:: gen-images/branch_label.svg
+    .. figure:: ../gen-images/branch_label.svg
       :width: 600
       :align: center
 
@@ -397,7 +397,7 @@ Region expressions
     would give a cable that starts and ends 20 μm and 80 μm along the branch
     respectively.
 
-    .. figure:: gen-images/cable_label.svg
+    .. figure:: ../gen-images/cable_label.svg
       :width: 600
       :align: center
 
@@ -414,7 +414,7 @@ Region expressions
     and up to ``extent`` μm from the location, measured as the distance traversed along cables between two locations.
     The distal interval of the locset ``start`` is the union of the distal interval of each location in ``start``.
 
-    .. figure:: gen-images/distint_label.svg
+    .. figure:: ../gen-images/distint_label.svg
       :width: 600
       :align: center
 
@@ -430,7 +430,7 @@ Region expressions
     When no ``extent`` distance is provided, the distal intervals are extended to all terminal
     locations that are distal to each location in ``start``.
 
-    .. figure:: gen-images/distintinf_label.svg
+    .. figure:: ../gen-images/distintinf_label.svg
       :width: 600
       :align: center
 
@@ -448,7 +448,7 @@ Region expressions
     and up to ``extent`` μm from the location, measured as the distance traversed along cables between two locations.
     The proximal interval of the locset ``start`` is the union of the proximal interval of each location in ``start``.
 
-    .. figure:: gen-images/proxint_label.svg
+    .. figure:: ../gen-images/proxint_label.svg
       :width: 600
       :align: center
 
@@ -463,7 +463,7 @@ Region expressions
 
     When no ``extent`` distance is provided, the proximal intervals are extended to the root location.
 
-    .. figure:: gen-images/proxintinf_label.svg
+    .. figure:: ../gen-images/proxintinf_label.svg
       :width: 600
       :align: center
 
@@ -478,7 +478,7 @@ Region expressions
 
     All parts of cable segments in the region ``reg`` with radius less than ``radius``.
 
-    .. figure:: gen-images/radiuslt_label.svg
+    .. figure:: ../gen-images/radiuslt_label.svg
       :width: 300
       :align: center
 
@@ -495,7 +495,7 @@ Region expressions
 
     All parts of cable segments in the region ``reg`` with radius less than or equal to ``radius``.
 
-    .. figure:: gen-images/radiusle_label.svg
+    .. figure:: ../gen-images/radiusle_label.svg
       :width: 300
       :align: center
 
@@ -511,7 +511,7 @@ Region expressions
 
     All parts of cable segments in the region ``reg`` with radius greater than ``radius``.
 
-    .. figure:: gen-images/radiusgt_label.svg
+    .. figure:: ../gen-images/radiusgt_label.svg
       :width: 300
       :align: center
 
@@ -528,7 +528,7 @@ Region expressions
 
     All parts of cable segments in the region ``reg`` with radius greater than or equal to ``radius``.
 
-    .. figure:: gen-images/radiusge_label.svg
+    .. figure:: ../gen-images/radiusge_label.svg
       :width: 300
       :align: center
 
@@ -544,7 +544,7 @@ Region expressions
 
     The union of two or more regions.
 
-    .. figure:: gen-images/union_label.svg
+    .. figure:: ../gen-images/union_label.svg
       :width: 900
       :align: center
 
@@ -554,7 +554,7 @@ Region expressions
 
     The intersection of two or more regions.
 
-    .. figure:: gen-images/intersect_label.svg
+    .. figure:: ../gen-images/intersect_label.svg
       :width: 900
       :align: center
 

doc/co_morphology.rst → doc/concepts/morphology.rst

@@ -85,7 +85,7 @@ tag 2 coloured grey for axon; tag 3 coloured blue for basal dendrites.
 
 .. _morph-label-seg-fig:
 
-.. figure:: gen-images/label_seg.svg
+.. figure:: ../gen-images/label_seg.svg
   :width: 600
   :align: center
 
@@ -108,7 +108,7 @@ axon and dendritic tree and the soma segment to which they attach.
 
 .. _morph-detached-seg-fig:
 
-.. figure:: gen-images/detached_seg.svg
+.. figure:: ../gen-images/detached_seg.svg
   :width: 600
   :align: center
 
@@ -136,7 +136,7 @@ uses 4 segments to model the soma.
 
 .. _morph-stacked-seg-fig:
 
-.. figure:: gen-images/stacked_seg.svg
+.. figure:: ../gen-images/stacked_seg.svg
   :width: 600
   :align: center
 
@@ -180,7 +180,7 @@ which is illustrated along with its branches below.
 
 .. _morph-label-morph-fig:
 
-.. figure:: gen-images/label_morph.svg
+.. figure:: ../gen-images/label_morph.svg
   :width: 800
   :align: center
 
@@ -218,7 +218,7 @@ Gaps between segments do not influence branch creation, hence branches
 can contain gaps between segments. Take the example of a morphology with
 a gap between the soma and the axon and dendritic trees:
 
-.. figure:: gen-images/detached_morph.svg
+.. figure:: ../gen-images/detached_morph.svg
   :width: 800
   :align: center
 
@@ -240,7 +240,7 @@ contain segments with different tags, which in our examples gives branches
 that contain both soma and dendrite segments. For example, when building the
 soma from multiple segments:
 
-.. figure:: gen-images/stacked_morph.svg
+.. figure:: ../gen-images/stacked_morph.svg
   :width: 800
   :align: center
 
@@ -298,7 +298,7 @@ with a radius of 2 μm, centred at the origin.
     tree.append(mnpos, mpoint(-2, 0, 0, 2), mpoint(2, 0, 0, 2), tag=1)
     morph = arbor.morphology(tree)
 
-.. figure:: gen-images/sphere_morph.svg
+.. figure:: ../gen-images/sphere_morph.svg
   :width: 400
   :align: center
 
@@ -319,7 +319,7 @@ This can be described using a single segment.
     tree.append(mnpos, mpoint(0, 0, 0, 1), mpoint(10, 0, 0, 0.5), tag=3)
     morph = arbor.morphology(tree)
 
-.. figure:: gen-images/branch_morph1.svg
+.. figure:: ../gen-images/branch_morph1.svg
   :width: 600
   :align: center
 
@@ -340,7 +340,7 @@ distinct cable segments:
     tree.append(2,     mpoint( 8.0,  0.0,  0.0, 0.6), mpoint(10.0,  0.0,  0.0, 0.5), tag=3)
     morph = arbor.morphology(tree)
 
-.. figure:: gen-images/branch_morph2.svg
+.. figure:: ../gen-images/branch_morph2.svg
   :width: 600
   :align: center
 
@@ -361,7 +361,7 @@ joining the segments together, such that the morphology with the gap is the same
     tree.append(2,     mpoint(10.0,  0.0,  0.0, 0.6), mpoint(12.0, 0.0,  0.0, 0.5), tag=3)
     morph = arbor.morphology(tree)
 
-.. figure:: gen-images/branch_morph3.svg
+.. figure:: ../gen-images/branch_morph3.svg
   :width: 600
   :align: center
 
@@ -381,7 +381,7 @@ The next example adds a discontinuity to the previous example between segments
     tree.append(2,     mpoint( 8.0,  0.0,  0.0, 0.3), mpoint(10.0,  0.0,  0.0, 0.5), tag=3)
     morph = arbor.morphology(tree)
 
-.. figure:: gen-images/branch_morph4.svg
+.. figure:: ../gen-images/branch_morph4.svg
   :width: 600
   :align: center
 
@@ -411,7 +411,7 @@ radius as the distal end of the parent.
     tree.append(0,     mpoint(15.0,-3.0, 0.0, 0.2), tag= 3)
     morph = arbor.morphology(tree)
 
-.. figure:: gen-images/yshaped_morph.svg
+.. figure:: ../gen-images/yshaped_morph.svg
   :width: 800
   :align: center
 
@@ -433,7 +433,7 @@ diameter equal to 6 μm, which has the same surface area as the sphere.
     morph = arbor.morphology(tree)
 
 
-.. figure:: gen-images/ysoma_morph1.svg
+.. figure:: ../gen-images/ysoma_morph1.svg
   :width: 900
   :align: center
 
@@ -461,7 +461,7 @@ so it has :data:`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.
 
-.. figure:: gen-images/ysoma_morph2.svg
+.. figure:: ../gen-images/ysoma_morph2.svg
   :width: 900
   :align: center
 
@@ -478,7 +478,7 @@ because it has two children: the dendrites attached to its distal end.
     More generally, segments at the root of the tree are connected electrically at their
     proximal ends.
 
-    .. figure:: gen-images/ysoma_morph3.svg
+    .. figure:: ../gen-images/ysoma_morph3.svg
       :width: 900
       :align: center
 

doc/cpp_overview.rst → doc/cpp/index.rst

 .. _cppoverview:
 
-Overview
+C++
 =========
 
 The C++ API is the recommended interface through which advanced users and HPC
@@ -10,3 +10,17 @@ Arbor makes a distinction between the **description** of a model, and the
 **execution** of a model.
 
 A :cpp:type:`arb::recipe` describes a model, and a :cpp:type:`arb::simulation` is an executable instantiation of a model.
+
+.. toctree::
+   :caption: C++ API:
+   :maxdepth: 2
+
+   recipe
+   cell
+   cable_cell
+   interconnectivity
+   hardware
+   domdec
+   simulation
+   profiler
+   neuroml