From aa8da38b3dd7831b29207f8ff07caa8fa71c4bd8 Mon Sep 17 00:00:00 2001
From: Brent Huisman <brenthuisman@users.noreply.github.com>
Date: Thu, 8 Oct 2020 18:29:33 +0200
Subject: [PATCH] Doc fixes (#1185)
Remove Python API ref page, Spack Install, fix some links
---
doc/conf.py | 7 -------
doc/cpp_recipe.rst | 2 +-
doc/gs_single_cell.rst | 39 ++++++++++++++++++++-------------------
doc/in_install.rst | 5 ++---
doc/in_python.rst | 2 +-
doc/index.rst | 2 --
doc/py_overview.rst | 2 +-
doc/py_recipe.rst | 2 +-
doc/py_reference.rst | 10 ----------
9 files changed, 26 insertions(+), 45 deletions(-)
delete mode 100644 doc/py_reference.rst
diff --git a/doc/conf.py b/doc/conf.py
index 86c5856b..cb1ceca4 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -2,13 +2,6 @@
# -*- coding: utf-8 -*-
import sys, os
-# Path to Python Binding (_arbor)
-try:
- sys.path.append(os.path.join(os.environ['OLDPWD'],"python"))
- import arbor
-except ImportError:
- autodoc_mock_imports = ['arbor._arbor']
-
html_static_path = ['static']
def setup(app):
diff --git a/doc/cpp_recipe.rst b/doc/cpp_recipe.rst
index 7dab8876..ef3d1214 100644
--- a/doc/cpp_recipe.rst
+++ b/doc/cpp_recipe.rst
@@ -142,7 +142,7 @@ See :ref:`cppcell`.
Synapses
--------
-See :ref:`cppsynapses`.
+See :ref:`cppinterconnectivity`.
Probes
------
diff --git a/doc/gs_single_cell.rst b/doc/gs_single_cell.rst
index 1565dd1a..6c1a2e61 100644
--- a/doc/gs_single_cell.rst
+++ b/doc/gs_single_cell.rst
@@ -12,8 +12,7 @@ This guide will walk through a series of single cell models of increasing comple
Links are provided to separate documentation that covers relevant topics in more detail.
In an interactive Python interpreter, you can use ``help()`` on any class or function to
-obtain some documentation. E.g.: ``help(arbor.gap_junction_connection)`` will print
-:class:`this<arbor._arbor.gap_junction_connection>`.
+obtain some documentation.
.. _single_soma:
@@ -57,15 +56,15 @@ Let's unpack that.
Step **(1)** above shows how the cell is represented using a :class:`arbor.segment_tree`
to which a single segment is added. Arbor's cell morphologies are constructed from a
-:ref:`segment tree<morph-segment_tree>` which is a list of segments, which are tapered
-cones with a *tag*. :meth:`arbor.segment_tree.append` takes 4 arguments, starting with
+segment tree which is a list of segments, which are tapered cones with a *tag*.
+:meth:`arbor.segment_tree.append` takes 4 arguments, starting with
the parent segment. The first segment added has no parent however, which is made clear by
using :class:`arbor.mnpos`. Then two :class:`arbor.mpoint` s are supplied, the proximal
and distal endpoints of the segment. Finally, an integer value can be supplied to tag the
segment for future reference.
-In step **(2)** a dictionary of labels is created using :class:`arbor.label_dict<arbor.
-_arbor.label_dict>`. Cell builders need to refer to *regions* and *locations* on a cell
+In step **(2)** a dictionary of labels is created using :class:`arbor.label_dict<arbor.label_dict>`.
+Cell builders need to refer to *regions* and *locations* on a cell
morphology. Arbor uses a domains specific language (DSL) to describe regions and
locations, which are given labels. We add two labels:
@@ -84,10 +83,10 @@ with the named regions and locations.
channels all over the surface of the cell. :meth:`arbor.cable_cell.paint` lets us
instruct Arbor to use HH dynamics on the region we've labelled soma and sort the details
out for us.
-* Other properties we do want to :meth:`arbor.cable_cell.place<arbor._arbor.cable_cell.place>`
- in a precise :class:`arbor.location<arbor._arbor.location>`. We place two things:
- an :class:`arbor.iclamp<arbor._arbor.iclamp>` with a duration of 2 ms and a current of
- 0.8 nA, starting at 10 ms. Then, add an :class:`arbor.spike_detector<arbor._arbor.spike_detector>`
+* Other properties we do want to :meth:`arbor.cable_cell.place<arbor.cable_cell.place>`
+ in a precise :class:`arbor.location<arbor.location>`. We place two things:
+ an :class:`arbor.iclamp<arbor.iclamp>` with a duration of 2 ms and a current of
+ 0.8 nA, starting at 10 ms. Then, add an :class:`arbor.spike_detector<arbor.spike_detector>`
with a threshold of -10 mV to the location we've labelled 'center'.
Single cell network
@@ -96,8 +95,8 @@ Single cell network
Great, we have defined our cell! Now, let's move to the network. Arbor can simulate
networks with multiple individual cells, connected together in a network. Single cell
models do not require the full *recipe* interface used to describing such network models,
-with many unique cells, network and gap junctions. Arbor provides a :class:`arbor.
-single_cell_model<arbor._arbor.single_cell_model>` helper that wraps a cell description,
+with many unique cells, network and gap junctions. Arbor provides a
+:class:`arbor.single_cell_model<arbor.single_cell_model>` helper that wraps a cell description,
and provides an interface for recording potentials and running the simulation.
.. code-block:: python
@@ -111,10 +110,11 @@ and provides an interface for recording potentials and running the simulation.
# (6) Run simulation for 100 ms of simulated activity.
m.run(tfinal=100)
-Step **(4)** instantiates the :class:`arbor.single_cell_model<arbor._arbor.single_cell_model>` with our single-compartment cell.
+Step **(4)** instantiates the :class:`arbor.single_cell_model<arbor.single_cell_model>`
+with our single-compartment cell.
-In step **(5)** a :meth:`arbor.single_cell_model.probe()<arbor._arbor.single_cell_model.
-probe>` is used to record variables from the model. Three pieces of information are
+In step **(5)** a :meth:`arbor.single_cell_model.probe()<arbor.single_cell_model.probe>`
+is used to record variables from the model. Three pieces of information are
provided: the type of quantity we want probed (voltage), the location where we want to
probe ('center'), and the frequency at which we want to sample (10kHz).
@@ -142,13 +142,14 @@ spike_detector and a voltage probe. Let's see what they have produced!
df = pandas.DataFrame({'t/ms': m.traces[0].time, 'U/mV': m.traces[0].value})
seaborn.relplot(data=df, kind="line", x="t/ms", y="U/mV").savefig('single_cell_model_result.svg')
-In step **(7)** we access :meth:`arbor.single_cell_model.spikes<arbor._arbor.
-single_cell_model.spikes>` to access the spike time. A single spike at a little over 10
+In step **(7)** we access :meth:`arbor.single_cell_model.spikes<arbor.single_cell_model.spikes>`
+to access the spike time. A single spike at a little over 10
ms should be printed, which matches the stimulus we have provided in step (3).
The other measurement we have is that of the potential, which we plot in step **(8)**.
-Arbor stores sampled quantities under :meth:`arbor.single_cell_model.traces<arbor._arbor.
-single_cell_model.traces>`. You should be seeing something like this:
+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
:width: 400
diff --git a/doc/in_install.rst b/doc/in_install.rst
index 02947d42..5b3d5da0 100644
--- a/doc/in_install.rst
+++ b/doc/in_install.rst
@@ -5,8 +5,7 @@ Install Arbor
Currently we offer three ways to get Arbor.
-1. **Python Package**. To get started quickly experimenting with Arbor via its Python API on your personal machine, see the :ref:`Python installation guide <gs_python>`.
-2. **Build and install from source**. To build and install Arbor, on your own machine or HPC environment, see :ref:`gs_build_install`.
-3. **Spack**. See :ref:`Spack installation guide <gs_spack>`.
+1. **Python Package**. To get started quickly experimenting with Arbor via 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 use Spack. Note that you can build the Python bindings with both of those as well.
diff --git a/doc/in_python.rst b/doc/in_python.rst
index 44753679..aa787ccc 100644
--- a/doc/in_python.rst
+++ b/doc/in_python.rst
@@ -119,7 +119,7 @@ below demonstrate this for both pip and ``setup.py``.
.. Note::
Detailed instructions on how to install using CMake are in the
:ref:`Python configuration <install-python>` section of the
- :ref:`installation guide <gs_install>`.
+ :ref:`installation guide <in_build_install>`.
CMake is recommended for developers, integration with package managers such as
Spack and EasyBuild, and users who require fine grained control over compilation
and installation.
diff --git a/doc/index.rst b/doc/index.rst
index 74e6158c..2885f177 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -29,7 +29,6 @@ Alternative citation formats for the paper can be `downloaded here <https://ieee
in_install
in_python
in_build_install
- in_spack
.. toctree::
:caption: Getting started:
@@ -67,7 +66,6 @@ Alternative citation formats for the paper can be `downloaded here <https://ieee
py_domdec
py_simulation
py_profiler
- py_reference
.. toctree::
:caption: C++ API
diff --git a/doc/py_overview.rst b/doc/py_overview.rst
index e85f374f..3375b1fe 100644
--- a/doc/py_overview.rst
+++ b/doc/py_overview.rst
@@ -6,7 +6,7 @@ The Python frontend for Arbor is an interface that the vast majority of users wi
This section covers how to use the frontend with examples and detailed descriptions of features.
.. Note::
- If you haven't set up Arbor yet, see the :ref:`Python installation guide <gs_python>`.
+ If you haven't set up Arbor yet, see the :ref:`Python installation guide <in_python>`.
.. _simsteps:
diff --git a/doc/py_recipe.rst b/doc/py_recipe.rst
index 73561f05..78d97fe3 100644
--- a/doc/py_recipe.rst
+++ b/doc/py_recipe.rst
@@ -111,7 +111,7 @@ See :ref:`pycell`.
Synapses
--------
-See :ref:`pysynapses`.
+See :ref:`pyinterconnectivity`.
Probes
------
diff --git a/doc/py_reference.rst b/doc/py_reference.rst
deleted file mode 100644
index bf0b84e9..00000000
--- a/doc/py_reference.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-Python API Reference
-====================
-
-This page contains the full Python API reference. You can safely leave out `._arbor` in your own code; it's autoimported into the `arbor` package. In an interactive Python interpreter, you can use ``help()`` on any class or function to obtain the documentation you read below. E.g. ``help(arbor.gap_junction_connection)`` will print :class:`this<arbor._arbor.gap_junction_connection>`.
-
-.. automodule:: arbor._arbor
- :members:
- :undoc-members:
- :special-members:
- :inherited-members:
--
GitLab