From 0ca102a7dcf77d88fcaf74883586a8f40b5424cd Mon Sep 17 00:00:00 2001
From: Brent Huisman <brenthuisman@users.noreply.github.com>
Date: Fri, 9 Oct 2020 15:57:47 +0200
Subject: [PATCH] Rearranged the documentation source to have nicer URLs on the
website. (#1188)
---
.readthedocs.yml | 9 ++-
.../cable_cell.rst} | 0
doc/{co_cell.rst => concepts/cell.rst} | 0
doc/{co_domdec.rst => concepts/domdec.rst} | 0
.../hardware.rst} | 0
doc/{co_overview.rst => concepts/index.rst} | 22 ++++-
.../interconnectivity.rst} | 6 +-
doc/{co_labels.rst => concepts/labels.rst} | 52 ++++++------
.../mechanisms.rst} | 0
.../morphology.rst} | 30 +++----
doc/{co_recipe.rst => concepts/recipe.rst} | 0
.../simulation.rst} | 0
.../cable_cell.rst} | 0
doc/{cpp_cell.rst => cpp/cell.rst} | 0
doc/{cpp_domdec.rst => cpp/domdec.rst} | 0
doc/{cpp_hardware.rst => cpp/hardware.rst} | 0
doc/{cpp_overview.rst => cpp/index.rst} | 16 +++-
.../interconnectivity.rst} | 0
doc/{cpp_neuroml.rst => cpp/neuroml.rst} | 0
doc/{cpp_profiler.rst => cpp/profiler.rst} | 0
doc/{cpp_recipe.rst => cpp/recipe.rst} | 0
.../simulation.rst} | 0
.../distributed_context.rst} | 0
doc/{cpp_dry_run.rst => hpc/dry_run.rst} | 0
doc/hpc/index.rst | 9 +++
doc/index.rst | 81 +++----------------
.../build_install.rst} | 0
doc/{in_install.rst => install/index.rst} | 13 ++-
doc/{in_python.rst => install/python.rst} | 0
doc/{in_spack.rst => install/spack.rst} | 0
doc/internals/index.rst | 14 ++++
doc/{ai_nmodl.rst => internals/nmodl.rst} | 0
.../sampling_api.rst} | 0
.../simd_api.rst} | 0
doc/{ai_library.rst => internals/util.rst} | 7 +-
.../cable_cell.rst} | 0
doc/{py_cell.rst => python/cell.rst} | 0
doc/{py_domdec.rst => python/domdec.rst} | 0
doc/{py_hardware.rst => python/hardware.rst} | 0
doc/{py_overview.rst => python/index.rst} | 24 +++++-
.../interconnectivity.rst} | 0
doc/{py_labels.rst => python/labels.rst} | 0
.../mechanisms.rst} | 0
.../morphology.rst} | 2 +-
doc/{py_profiler.rst => python/profiler.rst} | 0
doc/{py_recipe.rst => python/recipe.rst} | 0
.../simulation.rst} | 0
doc/requirements.txt | 2 +-
.../index.rst} | 8 +-
.../single_cell_model.rst} | 2 +-
.../single_cell_model_result.svg | 0
51 files changed, 160 insertions(+), 137 deletions(-)
rename doc/{co_cable_cell.rst => concepts/cable_cell.rst} (100%)
rename doc/{co_cell.rst => concepts/cell.rst} (100%)
rename doc/{co_domdec.rst => concepts/domdec.rst} (100%)
rename doc/{co_hardware.rst => concepts/hardware.rst} (100%)
rename doc/{co_overview.rst => concepts/index.rst} (84%)
rename doc/{co_interconnectivity.rst => concepts/interconnectivity.rst} (98%)
rename doc/{co_labels.rst => concepts/labels.rst} (94%)
rename doc/{co_mechanisms.rst => concepts/mechanisms.rst} (100%)
rename doc/{co_morphology.rst => concepts/morphology.rst} (96%)
rename doc/{co_recipe.rst => concepts/recipe.rst} (100%)
rename doc/{co_simulation.rst => concepts/simulation.rst} (100%)
rename doc/{cpp_cable_cell.rst => cpp/cable_cell.rst} (100%)
rename doc/{cpp_cell.rst => cpp/cell.rst} (100%)
rename doc/{cpp_domdec.rst => cpp/domdec.rst} (100%)
rename doc/{cpp_hardware.rst => cpp/hardware.rst} (100%)
rename doc/{cpp_overview.rst => cpp/index.rst} (68%)
rename doc/{cpp_interconnectivity.rst => cpp/interconnectivity.rst} (100%)
rename doc/{cpp_neuroml.rst => cpp/neuroml.rst} (100%)
rename doc/{cpp_profiler.rst => cpp/profiler.rst} (100%)
rename doc/{cpp_recipe.rst => cpp/recipe.rst} (100%)
rename doc/{cpp_simulation.rst => cpp/simulation.rst} (100%)
rename doc/{cpp_distributed_context.rst => hpc/distributed_context.rst} (100%)
rename doc/{cpp_dry_run.rst => hpc/dry_run.rst} (100%)
create mode 100644 doc/hpc/index.rst
rename doc/{in_build_install.rst => install/build_install.rst} (100%)
rename doc/{in_install.rst => install/index.rst} (69%)
rename doc/{in_python.rst => install/python.rst} (100%)
rename doc/{in_spack.rst => install/spack.rst} (100%)
create mode 100644 doc/internals/index.rst
rename doc/{ai_nmodl.rst => internals/nmodl.rst} (100%)
rename doc/{ai_sampling_api.rst => internals/sampling_api.rst} (100%)
rename doc/{ai_simd_api.rst => internals/simd_api.rst} (100%)
rename doc/{ai_library.rst => internals/util.rst} (87%)
rename doc/{py_cable_cell.rst => python/cable_cell.rst} (100%)
rename doc/{py_cell.rst => python/cell.rst} (100%)
rename doc/{py_domdec.rst => python/domdec.rst} (100%)
rename doc/{py_hardware.rst => python/hardware.rst} (100%)
rename doc/{py_overview.rst => python/index.rst} (82%)
rename doc/{py_interconnectivity.rst => python/interconnectivity.rst} (100%)
rename doc/{py_labels.rst => python/labels.rst} (100%)
rename doc/{py_mechanisms.rst => python/mechanisms.rst} (100%)
rename doc/{py_morphology.rst => python/morphology.rst} (99%)
rename doc/{py_profiler.rst => python/profiler.rst} (100%)
rename doc/{py_recipe.rst => python/recipe.rst} (100%)
rename doc/{py_simulation.rst => python/simulation.rst} (100%)
rename doc/{gs_other_examples.rst => tutorial/index.rst} (78%)
rename doc/{gs_single_cell.rst => tutorial/single_cell_model.rst} (99%)
rename doc/{images => tutorial}/single_cell_model_result.svg (100%)
diff --git a/.readthedocs.yml b/.readthedocs.yml
index b8fccfee..2baa5a9b 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 a962ae4a..a848bd49 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 168b4660..189cb202 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 678130dc..ba81e4e2 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 f07cbfe0..123562e3 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 78072d44..347f4fc4 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 00000000..bc9527d5
--- /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 71613323..de274d7b 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 1d1c01a9..4feaa830 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 00000000..94f53a6f
--- /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 8ca7bf49..d9a35ce4 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 3375b1fe..2be8f489 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 972deeeb..046eef2d 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 9135cbf4..c4e36347 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 139ce280..9ba16626 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 75b6f89e..caadeac7 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
--
GitLab