Doc fixes (#1185)

Remove Python API ref page, Spack Install, fix some links

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):

doc/cpp_recipe.rst

@@ -142,7 +142,7 @@ See :ref:`cppcell`.
 Synapses
 --------
 
-See :ref:`cppsynapses`.
+See :ref:`cppinterconnectivity`.
 
 Probes
 ------

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

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.

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.

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

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:
 

doc/py_recipe.rst

@@ -111,7 +111,7 @@ See :ref:`pycell`.
 Synapses
 --------
 
-See :ref:`pysynapses`.
+See :ref:`pyinterconnectivity`.
 
 Probes
 ------

doc/py_reference.rst

-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: