docs: modernize documentation with layered Arbor-inspired architecture

.gitignore

@@ -164,6 +164,7 @@ examples/neuron_compare/channel_no_conc/artifacts/
 # IPython
 profile_default/
 ipython_config.py
+/docs/apis/changelog.md
 
 # pyenv
 #   For a library or package, you might want to ignore these files since the code is
@@ -247,3 +248,5 @@ x86_64/
 docs/_brand/
 docs/_static/css/brainx-header.css
 docs/_static/js/brainx-header.js
+/docs/_static/css/brainx-footer.css
+/docs/_static/js/brainx-footer.js

README.md

@@ -112,8 +112,8 @@ cell.place(RootLocation(0.5), mech.CurrentClamp.step(0.2 * u.nA, duration=50 * u
 import braincell
 import braincell.vis as vis
 
-# Load from NeuroMorpho.Org (cached locally)
-morpho = braincell.load_neuromorpho("cnic_001")
+# Load from NeuroMorpho.Org by neuron id (downloaded and cached locally)
+morpho = braincell.Morphology.from_neuromorpho(12345)
 
 # 2-D layout plot
 vis.plot2d(morpho)

docs/apis/filter.rst

@@ -0,0 +1,77 @@
+``braincell.filter`` module
+===========================
+
+.. currentmodule:: braincell.filter
+.. automodule:: braincell.filter
+
+``braincell.filter`` provides the selection algebra used to say *where* on a
+cell a mechanism is installed. **Regions** select extended sets of cable (paint
+targets); **locsets** select sets of points (place targets). Both compose
+through union / intersection / difference. See
+:doc:`../concepts/regions_locsets` for the conceptual guide.
+
+
+Regions
+-------
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+   :template: classtemplate.rst
+
+    RegionExpr
+    AllRegion
+    EmptyRegion
+    SubtreeRegion
+    BranchRangeFilter
+    BranchInFilter
+    BranchSlice
+    RadiusRangeRegion
+    EuclideanDistanceRegion
+    TreeDistanceRegion
+    RegionAnchors
+    RegionMask
+    RegionSetOp
+
+
+Locsets
+-------
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+   :template: classtemplate.rst
+
+    LocsetExpr
+    RootLocation
+    Terminals
+    BranchPoints
+    UniformSamples
+    StepSamples
+    RandomSamples
+    AtLocation
+    LocsetMask
+    LocsetSetOp
+
+
+Helpers
+-------
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+    branch_in
+    branch_range
+    at
+
+
+Caching
+-------
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+   :template: classtemplate.rst
+
+    SelectionCache

docs/apis/io.rst

@@ -0,0 +1,107 @@
+``braincell.io`` module
+=======================
+
+.. currentmodule:: braincell.io
+.. automodule:: braincell.io
+
+``braincell.io`` reads neuronal morphologies from the common file formats and
+integrates with `NeuroMorpho.Org <https://neuromorpho.org>`_. See
+:doc:`../file_formats/index` for the task-oriented guide.
+
+
+SWC
+---
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+   :template: classtemplate.rst
+
+    SwcReader
+    SwcReadOptions
+    SwcReport
+    SwcIssue
+
+
+Neurolucida ASC
+---------------
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+   :template: classtemplate.rst
+
+    AscReader
+    AscReport
+    AscIssue
+    AscMetadata
+    AscSpineRecord
+
+
+NeuroML2
+--------
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+   :template: classtemplate.rst
+
+    NeuroMlReader
+
+
+NeuroMorpho.Org client
+----------------------
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+    load_neuromorpho
+    fetch_neuromorpho
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+   :template: classtemplate.rst
+
+    NeuroMorphoClient
+    NeuroMorphoQuery
+    NeuroMorphoNeuron
+    NeuroMorphoMeasurement
+    NeuroMorphoDetail
+    NeuroMorphoFilePlan
+    NeuroMorphoDownloadItem
+    NeuroMorphoDownloadRecord
+    NeuroMorphoUrls
+    NeuroMorphoSearchPage
+    NeuroMorphoCache
+    NeuroMorphoCacheLayout
+    NeuroMorphoCacheStatus
+
+
+Errors
+------
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+   :template: classtemplate.rst
+
+    NeuroMorphoError
+    NeuroMorphoHTTPError
+    NeuroMorphoNotFoundError
+    CheckpointError
+    CheckpointVersionError
+
+
+Checkpointing
+-------------
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+    save_morpho
+    load_morpho
+    save_branch
+    load_branch