Plan for documentation.

[brenthuisman]

This is a TODO for all things I'd like to update in/about the docs. The word "section" I use to refer to header/grouping on the readthedocs navigation sidebar.

• "How does arbor work?" is about concepts
  • This section now is getting a large number of pages, break out some? A cell section? we can go into detail such as cell types vs morpho/mech/junctions?
  • Rename and reorg Common Types pages. They reflect roughly the content under Concepts>Network Components.
    • Probes can have their own page, seems important?
    • reflect some of this into Python/C++ API pages, contributes to fixing Documentation for spikes and events #474
    • Update c++ recipe page Fix recipe docs for probes #1080
  • Cell kinds: 4 hard coded, only cable cell is morphologically detailed.
• Would be nice to have: classindex, functionindex: Sphinx does not provide this, just a moduleindex.
  • C++: use doxygen
    • breathe runs into a documented issue. Trouble is, we don't set -j for sphinx-build, so what's going on?
    • exhale uses breathe, supposedly easier to make indices. Used/created by some of the spack people. However, trips over macros and decorators (CUDA).
  • Python: autodoc. Doesn't do constants. Multiple definitions in Sphinx: There is a proposal to allow them, for synopses. Having a reference page alongside other documentation refer to the same code makes it a guarantee to have these warnings.
• (user/python) example-section: some lines of increasing complexity: (solves Tutorial: create an Arbor Python tutorial #877 Documentation: missing information about examples. #1107 )
  • cell complexity
  • interconnectivity
  • cell types
  • At minimum, explain how to find and use current examples
    • update existing ones to fix [Arbor 0.3.1-dev] No add_sphere attribute in flat_cell_builder() #1129
  • remove all traces of flat_cell_builder
    • ring.py
    • single_cell_builder.py

• stitches (sam)
• cable cell is quite saturated, break out some more? at least in the c++ api
  • cpp_cable_cell.html: TODO: describe other place-able things: current clamps, gap junction sites, threshold potential measurement point.
  • Super clear!
  • explain somewhere painting vs placing.