<!-- Please make sure your PR follows our [contribution
guidelines](https://github.com/arbor-sim/arbor/tree/master/doc/contrib)
and agree to the terms outlined in the [PR
procedure](https://github.com/arbor-sim/arbor/tree/master/doc/contrib/pr.rst).
-->

Since NMODL documentation is scarce and outdated, add a lengthy tutorial
about it.

The core issue here is to add units to the user facing API. I decided on
using the LLNL/units
library, which offers conversion and checking at runtime. Runtime is a
requirement -- as much
as I love static guarantees --, but keeping the interface uniform
between Python and C++ is a
must.

While setting this up, I noticed the severe lack of IDE/LSP support for
Arbor, so I added typing
stubs using https://github.com/sizmailov/pybind11-stubgen

. The
conjunction of typing and units
exposed misuse of pybind11 in several places, so next I had to massage
the ordering of bindings,
adjust the specification of default arguments, and add the odd missing
binding.

The schedule/event generator interface was tightened up, hiding the
`*_impl` structs and exposing
only the type erased `schedule` object. That in turn required
de-generification of the Poisson
schedule. Now, Mersenne twister is the only choice and I will remove
that later on for the CBRNG
we are already using elsewhere.

Currently, units are used for:
- [X] simulation
- [X] schedule/generator
- [x] paintables
- [X] placeables
  - [X] iclamp
  - [X] threshold
- [X] connections
- [X] gap junctions

Adding units to mechanism interfaces is _interesting_ but requires more
work and thought, so
I'll defer that to a later point in time. We'd need to adjust modcc to
expose and **check** units
and devise a scheme to handle missing units.

Generic TODOs; some might spin off into separate issues.
- [x] ~~rename py::iclamp OR cpp::i_clamp for consistency~~ covered by
#2239
- [x] use scale/base for iexpr paintables for consistency with
scaled_mech
- [x] ~~Use CBRNG for Poisson schedule~~ covered by #2243 
- [ ] Automate stub generation. A wishlist item, requires installing
extra software.
- [x] Properly integrate units w/ spack. NB. Units doesn't have a
spackage.

Closes #1983 
Closes #2032

---------

Co-authored-by: boeschf <48126478+boeschf@users.noreply.github.com>

- BREAKING: Rename spike detector -> threshold detector in Python
- `spike_detector` is still around, will throw a deprecation error; will be removed 0.9
- this brings Python closer to the C++ API and removes lots of ambiguities in the docs.

- Fix line numbers in tutorials, fallout from #1906
- Mention arbor-contrib in a few relevant places
- Correct some fallout from #1904
- A new hardware and profiling tutorial, and covers things moved out of other examples in #1904
- Various other documentation fixes

# Changes

- `cable_cell_global_properties` now holds a catalogue directy
- fixes for tests, examples, and python bindings accordingly

# Linked Issues
Fixes #1446 

Adds support for user-defined gap junction mechanisms. Fixes #1600.

- API Change: Wrap `mechanism_desc` in one of `density`, `synapse`, `junction` to be able to differentiate the kind of placed mechanism between point and junction mechanisms. 
- API Change: The `ggap` parameter of a `gap_junction_connection` renamed to `weight` and is not a unit-less parameter. 
- Mechanism ABI change: New `peer_index` vector which stores the indices of the peer sites of a gap-junction-connection. New mechanism kind. 
- Internal API change: `shared_state` no longer controls the gap junction current contribution, that is now handled in the mechanism callbacks.
- Modcc change: Add `JUNCTION_PROCESS` and `v_peer` keywords to nmodl, the first to identify a gap-junction mechanism, the second to access the peer voltage of a gap-junction connection. Modify modcc to be able to compile nmodl and generate correct code.
- Behavior change: gap-junctions now contribute to both the current and conductance of a CV as opposed to just the current.
- Add new "gj" mechanism, to replace the built-in constant-conductance based linear gap-junction implementation.
- Fix unit tests.
- Fix python wrapper. 
- Fix docs. 

* added notes re literal_include to python examples
* merged changes in #1504 
* deduped and includified (https://github.com/arbor-sim/arbor/pull/1558) tutorials.
* First divergence of tutorial and code spotted!
* Added some contrib documentation for examples and docs.

New structs and types:
* `cell_tag_type` (std::string): for labelling placeable items on a cell. The label refers to a number of items placed on a locset, equal to the number of locations in a locset. The number of locations in not always known to the user, so the previous way of using indices for items was no longer sufficient. 
* `lid_selection_policy`: for allowing a user to select a single item from a group of items sharing a label. Currently only `round_robin` and `assert_univalent` are supported. 
* `cell_local_label_type` and `cell_global_label_type`: for identifying the target and source of a connection or gap_junction connection. 
* `cell_label_ranges`, and `cell_labels_and_gids`: for propagating information about the labelled items on the cell from the cell groups back to the simulation and communicator. 
* `label_resolution_map` and `resolver`: for selecting an item (and retaining state) from a labelled group of items on a cell according to a user-selected policy.

Changes to the model-initialization: 
* The `communicator` now needs `label_resolution_maps` constructed from the cell group data in order to build the `connections` vectors. 
* The `simulation_state` object handles the transfer of the information when it is constructed. 
* Spike exchange at runtime remains unchanged, because `communicator::connections` remains unchanged. 

Changes to cells, cell_groups and recipe:
* `decor::place` expects a third label parameter, no longer returns an `lid_range`.
* `lif`, `source`, and `benchmark` cells need source/target labels in their constructors. 
* A `cell_group` needs to save data about the gid/labels/lid_ranges of each cell, to propagate back to the `communicator` constructor. 
* Connections/gap junction connections are formed between {label, policy} pairs on cells instead of indices. 
* `num_sources`, `num_targets`, `num_gap_junction_sites` deleted from `recipe`.

Additional changes:
* Add MPI wrapper for exchanging vectors of strings. 
* Corresponding updates to unit tests, Python wrapper, C++ and Python examples, documentation.

Fixes #1394

Co-authored-by: C.A.P. Linssen <charl@turingbirds.com>

* Add Python version of brunel.cpp example.
* Enforce consistency in units: both C++ and Python APIs use unit `kHz` for all frequencies.
* Align Python version `poisson_schedule` signature with C++ equivalent.
* Update unit tests to suit API changes.
* Update documentation to suit, along with minor additions related to networks and interconnectivity.
* Add `brunel.py` to `basic.yml` tests

* Tutorial ring network added. A few typos fixed, crosslinks fixed.
* MPI tutorial added.
* Improved SVG generation, added separate label scaling, increased default label size.
* Bugfix: didnt generate cable region in gen-labels.py used in `concepts/morphology.rst`.
* Termified Interconnectivity page.
* Termified probe nomenclature page. Will be moved in [this PR](https://github.com/arbor-sim/arbor/issues/1353) from python/simulation to concepts/probes_samplers.

* Add docs tutorial page for single_cell_recipe.py example
* Adapted single_cell_recipe.py slightly
* Improved labels and fixed some broken cross-linking
* Fixed a typo here and there

* Add 2 new examples to `python/examples` and their corresponding tutorials in the docs. 
    1. `single_cell_detailed.py` : a slightly more complex example using `single_cell_model`
    2. `single_cell_detailed_recipe.py`: equivalent to `single_cell_detailed.py` but using a recipe. 
* Change `load_swc`-> `load_swc_arbor` for consistency.
* Run Sphinx with specified PYTHON_EXECUTABLE.
* Set PYTHONPATH env var in doc/CMakeLists.txt, such that it propagates correctly, including locally.
* Build pyarb BEFORE html such that docs build can import arbor in Github Actions script.