diff --git a/.readthedocs.yml b/.readthedocs.yml
index b8fccfee955769597aae375080063fd0d093a853..2baa5a9bbc6a2061cb4ae31223691f4e6a8599f8 100644
--- a/.readthedocs.yml
+++ b/.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
diff --git a/doc/co_cable_cell.rst b/doc/concepts/cable_cell.rst
similarity index 100%
rename from doc/co_cable_cell.rst
rename to doc/concepts/cable_cell.rst
diff --git a/doc/co_cell.rst b/doc/concepts/cell.rst
similarity index 100%
rename from doc/co_cell.rst
rename to doc/concepts/cell.rst
diff --git a/doc/co_domdec.rst b/doc/concepts/domdec.rst
similarity index 100%
rename from doc/co_domdec.rst
rename to doc/concepts/domdec.rst
diff --git a/doc/co_hardware.rst b/doc/concepts/hardware.rst
similarity index 100%
rename from doc/co_hardware.rst
rename to doc/concepts/hardware.rst
diff --git a/doc/co_overview.rst b/doc/concepts/index.rst
similarity index 84%
rename from doc/co_overview.rst
rename to doc/concepts/index.rst
index a962ae4aebf3f3b782d2080aac12fc58110fb49b..a848bd49744a271a1ee12b4d3eb11980fd8d51a8 100644
--- a/doc/co_overview.rst
+++ b/doc/concepts/index.rst
@@ -1,7 +1,10 @@
.. _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
diff --git a/doc/co_interconnectivity.rst b/doc/concepts/interconnectivity.rst
similarity index 98%
rename from doc/co_interconnectivity.rst
rename to doc/concepts/interconnectivity.rst
index 168b4660a1e522e2bf9e28ebcf6a560cc2d72254..189cb202c02cb03de34bd565c7a8365ad8fd1819 100644
--- a/doc/co_interconnectivity.rst
+++ b/doc/concepts/interconnectivity.rst
@@ -1,7 +1,7 @@
.. _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.
diff --git a/doc/co_labels.rst b/doc/concepts/labels.rst
similarity index 94%
rename from doc/co_labels.rst
rename to doc/concepts/labels.rst
index 678130dc36d436d3fadd392f3340b83d4cf069b9..ba81e4e2584cd8a9fab386775108713bfed59e27 100644
--- a/doc/co_labels.rst
+++ b/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
diff --git a/doc/co_mechanisms.rst b/doc/concepts/mechanisms.rst
similarity index 100%
rename from doc/co_mechanisms.rst
rename to doc/concepts/mechanisms.rst
diff --git a/doc/co_morphology.rst b/doc/concepts/morphology.rst
similarity index 96%
rename from doc/co_morphology.rst
rename to doc/concepts/morphology.rst
index f07cbfe0502b54d712847842bf875a39bcb567bf..123562e33d2f17bc12bc5c311a96dd74eabad5f7 100644
--- a/doc/co_morphology.rst
+++ b/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
diff --git a/doc/co_recipe.rst b/doc/concepts/recipe.rst
similarity index 100%
rename from doc/co_recipe.rst
rename to doc/concepts/recipe.rst
diff --git a/doc/co_simulation.rst b/doc/concepts/simulation.rst
similarity index 100%
rename from doc/co_simulation.rst
rename to doc/concepts/simulation.rst
diff --git a/doc/cpp_cable_cell.rst b/doc/cpp/cable_cell.rst
similarity index 100%
rename from doc/cpp_cable_cell.rst
rename to doc/cpp/cable_cell.rst
diff --git a/doc/cpp_cell.rst b/doc/cpp/cell.rst
similarity index 100%
rename from doc/cpp_cell.rst
rename to doc/cpp/cell.rst
diff --git a/doc/cpp_domdec.rst b/doc/cpp/domdec.rst
similarity index 100%
rename from doc/cpp_domdec.rst
rename to doc/cpp/domdec.rst
diff --git a/doc/cpp_hardware.rst b/doc/cpp/hardware.rst
similarity index 100%
rename from doc/cpp_hardware.rst
rename to doc/cpp/hardware.rst
diff --git a/doc/cpp_overview.rst b/doc/cpp/index.rst
similarity index 68%
rename from doc/cpp_overview.rst
rename to doc/cpp/index.rst
index 78072d448013adfa1d71e012941e47be76c05f21..347f4fc42a065f8de7b84321234a0b5ebdb68b1e 100644
--- a/doc/cpp_overview.rst
+++ b/doc/cpp/index.rst
@@ -1,6 +1,6 @@
.. _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
diff --git a/doc/cpp_interconnectivity.rst b/doc/cpp/interconnectivity.rst
similarity index 100%
rename from doc/cpp_interconnectivity.rst
rename to doc/cpp/interconnectivity.rst
diff --git a/doc/cpp_neuroml.rst b/doc/cpp/neuroml.rst
similarity index 100%
rename from doc/cpp_neuroml.rst
rename to doc/cpp/neuroml.rst
diff --git a/doc/cpp_profiler.rst b/doc/cpp/profiler.rst
similarity index 100%
rename from doc/cpp_profiler.rst
rename to doc/cpp/profiler.rst
diff --git a/doc/cpp_recipe.rst b/doc/cpp/recipe.rst
similarity index 100%
rename from doc/cpp_recipe.rst
rename to doc/cpp/recipe.rst
diff --git a/doc/cpp_simulation.rst b/doc/cpp/simulation.rst
similarity index 100%
rename from doc/cpp_simulation.rst
rename to doc/cpp/simulation.rst
diff --git a/doc/cpp_distributed_context.rst b/doc/hpc/distributed_context.rst
similarity index 100%
rename from doc/cpp_distributed_context.rst
rename to doc/hpc/distributed_context.rst
diff --git a/doc/cpp_dry_run.rst b/doc/hpc/dry_run.rst
similarity index 100%
rename from doc/cpp_dry_run.rst
rename to doc/hpc/dry_run.rst
diff --git a/doc/hpc/index.rst b/doc/hpc/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..bc9527d5914d9279fe342378a66d8c9c5d132537
--- /dev/null
+++ b/doc/hpc/index.rst
@@ -0,0 +1,9 @@
+HPC
+===
+
+.. toctree::
+ :caption: C++ API for HPC:
+ :maxdepth: 2
+
+ distributed_context
+ dry_run
diff --git a/doc/index.rst b/doc/index.rst
index 71613323cf036a3652265742b7f83d8e0d1846af..de274d7bf12d723e49c0a818a61f6d14b19c9214 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -31,74 +31,13 @@ Citing Arbor
Alternative citation formats for the paper can be `downloaded here <https://ieeexplore.ieee.org/abstract/document/8671560>`_, and a preprint is available at `arXiv <https://arxiv.org/abs/1901.07454>`_.
.. toctree::
- :caption: Get Arbor:
-
- in_install
- in_python
- in_build_install
-
-.. toctree::
- :caption: Getting started:
-
- gs_single_cell
- gs_other_examples
-
-.. toctree::
- :caption: How does Arbor work?
-
- co_overview
- co_recipe
- co_cell
- co_cable_cell
- co_morphology
- co_labels
- co_mechanisms
- co_interconnectivity
- co_hardware
- co_domdec
- co_simulation
-
-.. toctree::
- :caption: Python API
-
- py_overview
- py_recipe
- py_cell
- py_cable_cell
- py_morphology
- py_labels
- py_mechanisms
- py_interconnectivity
- py_hardware
- py_domdec
- py_simulation
- py_profiler
-
-.. toctree::
- :caption: C++ API
-
- cpp_overview
- cpp_recipe
- cpp_cell
- cpp_cable_cell
- cpp_interconnectivity
- cpp_hardware
- cpp_domdec
- cpp_simulation
- cpp_profiler
- cpp_neuroml
-
-.. toctree::
- :caption: C++ API for HPC
-
- cpp_distributed_context
- cpp_dry_run
-
-.. toctree::
- :caption: Arbor Internals
-
- ai_library
- ai_nmodl
- ai_simd_api
- ai_sampling_api
-
+ :caption: Arbor documentation:
+ :maxdepth: 1
+
+ install/index
+ tutorial/index
+ concepts/index
+ python/index
+ cpp/index
+ hpc/index
+ internals/index
diff --git a/doc/in_build_install.rst b/doc/install/build_install.rst
similarity index 100%
rename from doc/in_build_install.rst
rename to doc/install/build_install.rst
diff --git a/doc/in_install.rst b/doc/install/index.rst
similarity index 69%
rename from doc/in_install.rst
rename to doc/install/index.rst
index 1d1c01a92ef120bf44303a8abbf0b587cede9d3a..4feaa8300940fd710bea3d6ec29d41cf4b8686d7 100644
--- a/doc/in_install.rst
+++ b/doc/install/index.rst
@@ -1,11 +1,18 @@
.. _in_install:
-Install Arbor
-#############################
+Get Arbor
+=========
Currently we offer three ways to get Arbor.
1. **Python Package**. To get started quickly with Arbor using its Python API on your personal machine, see the :ref:`Python installation guide <in_python>`.
2. **Build and install from source**. To build and install Arbor, on your own machine or HPC environment, see :ref:`in_build_install`.
-If you wish to use the C++ API, you'll need to build Arbor from source or using Spack. Note that you can also build the Python bindings using these methods.
+If you wish to use the C++ API, you'll need to build Arbor from source. Note that you can build the Python bindings with both of those as well.
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Install Arbor:
+
+ python
+ build_install
diff --git a/doc/in_python.rst b/doc/install/python.rst
similarity index 100%
rename from doc/in_python.rst
rename to doc/install/python.rst
diff --git a/doc/in_spack.rst b/doc/install/spack.rst
similarity index 100%
rename from doc/in_spack.rst
rename to doc/install/spack.rst
diff --git a/doc/internals/index.rst b/doc/internals/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..94f53a6f4c26f38a8a08522e92a83a172f3808ac
--- /dev/null
+++ b/doc/internals/index.rst
@@ -0,0 +1,14 @@
+Internals
+=========
+
+Here we document internal components of Arbor. These pages can be useful if you're interested in developing on Arbor itself.
+
+.. toctree::
+ :caption: Arbor Internals:
+ :maxdepth: 2
+
+ util
+ nmodl
+ simd_api
+ sampling_api
+
diff --git a/doc/ai_nmodl.rst b/doc/internals/nmodl.rst
similarity index 100%
rename from doc/ai_nmodl.rst
rename to doc/internals/nmodl.rst
diff --git a/doc/ai_sampling_api.rst b/doc/internals/sampling_api.rst
similarity index 100%
rename from doc/ai_sampling_api.rst
rename to doc/internals/sampling_api.rst
diff --git a/doc/ai_simd_api.rst b/doc/internals/simd_api.rst
similarity index 100%
rename from doc/ai_simd_api.rst
rename to doc/internals/simd_api.rst
diff --git a/doc/ai_library.rst b/doc/internals/util.rst
similarity index 87%
rename from doc/ai_library.rst
rename to doc/internals/util.rst
index 8ca7bf49f0cc96fb1ee554822daa5327d21e1c7d..d9a35ce40630541ef8085327e1e7b63d80dcf4d2 100644
--- a/doc/ai_library.rst
+++ b/doc/internals/util.rst
@@ -1,12 +1,7 @@
.. _libref:
-Library reference
-#################
-
-Low level library reference material goes here, e.g. `range` library documentation.
-
Utility wrappers and containers
---------------------------------
+##################################
.. cpp:namespace:: arb::util
diff --git a/doc/py_cable_cell.rst b/doc/python/cable_cell.rst
similarity index 100%
rename from doc/py_cable_cell.rst
rename to doc/python/cable_cell.rst
diff --git a/doc/py_cell.rst b/doc/python/cell.rst
similarity index 100%
rename from doc/py_cell.rst
rename to doc/python/cell.rst
diff --git a/doc/py_domdec.rst b/doc/python/domdec.rst
similarity index 100%
rename from doc/py_domdec.rst
rename to doc/python/domdec.rst
diff --git a/doc/py_hardware.rst b/doc/python/hardware.rst
similarity index 100%
rename from doc/py_hardware.rst
rename to doc/python/hardware.rst
diff --git a/doc/py_overview.rst b/doc/python/index.rst
similarity index 82%
rename from doc/py_overview.rst
rename to doc/python/index.rst
index 3375b1fee83c4acb2b035bd6f161051ebc68c0bc..2be8f489c7695d4b3eae5e4298d41b0749ee083a 100644
--- a/doc/py_overview.rst
+++ b/doc/python/index.rst
@@ -1,7 +1,8 @@
.. _pyoverview:
-Overview
+Python
=========
+
The Python frontend for Arbor is an interface that the vast majority of users will use to interact with Arbor.
This section covers how to use the frontend with examples and detailed descriptions of features.
@@ -10,8 +11,7 @@ This section covers how to use the frontend with examples and detailed descripti
.. _simsteps:
-Simulation steps
-~~~~~~~~~~~~~~~~
+.. rubric:: Simulation steps
The workflow for defining and running a model defined in :ref:`modelsimulation` can be performed
in Python as follows:
@@ -25,7 +25,7 @@ These details are described and examples are given in the next sections :ref:`py
.. note::
- Detailed information on Arbor's python features can also be obtained with Python's ``help`` function, e.g.
+ Detailed information on Arbor's Python features can also be obtained with Python's ``help`` function, e.g.
.. code-block:: python3
@@ -35,3 +35,19 @@ These details are described and examples are given in the next sections :ref:`py
class proc_allocation(pybind11_builtins.pybind11_object)
| Enumerates the computational resources on a node to be used for simulation.
|...
+
+.. toctree::
+ :caption: Python API:
+ :maxdepth: 2
+
+ recipe
+ cell
+ cable_cell
+ morphology
+ labels
+ mechanisms
+ interconnectivity
+ hardware
+ domdec
+ simulation
+ profiler
diff --git a/doc/py_interconnectivity.rst b/doc/python/interconnectivity.rst
similarity index 100%
rename from doc/py_interconnectivity.rst
rename to doc/python/interconnectivity.rst
diff --git a/doc/py_labels.rst b/doc/python/labels.rst
similarity index 100%
rename from doc/py_labels.rst
rename to doc/python/labels.rst
diff --git a/doc/py_mechanisms.rst b/doc/python/mechanisms.rst
similarity index 100%
rename from doc/py_mechanisms.rst
rename to doc/python/mechanisms.rst
diff --git a/doc/py_morphology.rst b/doc/python/morphology.rst
similarity index 99%
rename from doc/py_morphology.rst
rename to doc/python/morphology.rst
index 972deeeb42ab880b9c54d6999f36c18c37194ae5..046eef2df0b97fbe95eea160f42233c7dcd3d44b 100644
--- a/doc/py_morphology.rst
+++ b/doc/python/morphology.rst
@@ -167,7 +167,7 @@ Cell morphology
take the segment tree used in the :ref:`documentation above <morph-label-seg-fig>`.
- .. figure:: gen-images/label_seg.svg
+ .. figure:: ../gen-images/label_seg.svg
Which is constructed as follows.
diff --git a/doc/py_profiler.rst b/doc/python/profiler.rst
similarity index 100%
rename from doc/py_profiler.rst
rename to doc/python/profiler.rst
diff --git a/doc/py_recipe.rst b/doc/python/recipe.rst
similarity index 100%
rename from doc/py_recipe.rst
rename to doc/python/recipe.rst
diff --git a/doc/py_simulation.rst b/doc/python/simulation.rst
similarity index 100%
rename from doc/py_simulation.rst
rename to doc/python/simulation.rst
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 9135cbf4b19ea13099e3b1162804ed6dfdf140d5..c4e363475fc7c5aa3fadbe0113a1f914ccc12ce0 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,2 +1,2 @@
sphinx>=2.3.0
-svgwrite
\ No newline at end of file
+svgwrite
diff --git a/doc/gs_other_examples.rst b/doc/tutorial/index.rst
similarity index 78%
rename from doc/gs_other_examples.rst
rename to doc/tutorial/index.rst
index 139ce2807327d5f47c57ab26fe7d060dcd828093..9ba16626cdc3b105b48983d19bdf5428d421ee79 100644
--- a/doc/gs_other_examples.rst
+++ b/doc/tutorial/index.rst
@@ -1,6 +1,6 @@
.. _gs_other_examples:
-Other examples
+Quick start
================================
.. Note::
@@ -8,3 +8,9 @@ Other examples
.. Todo::
Add more in-depth tutorial-like pages building up examples here.
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Tutorials
+
+ single_cell_model
\ No newline at end of file
diff --git a/doc/gs_single_cell.rst b/doc/tutorial/single_cell_model.rst
similarity index 99%
rename from doc/gs_single_cell.rst
rename to doc/tutorial/single_cell_model.rst
index 75b6f89ea664372e9801524d6ebdeb6c5372218f..caadeac7c82dca79344316e56f2acd09ecdf0593 100644
--- a/doc/gs_single_cell.rst
+++ b/doc/tutorial/single_cell_model.rst
@@ -149,7 +149,7 @@ The other measurement we have is that of the potential, which we plot in step **
Arbor stores sampled quantities under :meth:`arbor.single_cell_model.traces<arbor.single_cell_model.traces>`.
You should be seeing something like this:
-.. figure:: images/single_cell_model_result.svg
+.. figure:: single_cell_model_result.svg
:width: 400
:align: center
diff --git a/doc/images/single_cell_model_result.svg b/doc/tutorial/single_cell_model_result.svg
similarity index 100%
rename from doc/images/single_cell_model_result.svg
rename to doc/tutorial/single_cell_model_result.svg