Use Sqhinx docs instead of mkdocs (jaxleyverse#434)

* make comp_edges private

* Start using sqhinx docs

* add old docs as `mkdocs`

* fixup

* automated mkdocs building

.github/workflows/build_docs.yml

@@ -35,19 +35,19 @@ jobs:
         python -m pip install .[doc]
     - name: convert notebooks to markdown
       run: |
-        cd docs
-        jupyter nbconvert --to markdown ../tutorials/*.ipynb --output-dir docs/tutorials/
+        cd mkdocs
+        jupyter nbconvert --to markdown ../docs/tutorials/*.ipynb --output-dir docs/tutorial/
     - name: Configure Git user for bot
       run: |
         git config --local user.email "github-actions[bot]@users.noreply.github.com"
         git config --local user.name "github-actions[bot]"
     - name: Build and deploy dev documentation upon push to main
       if: ${{ github.event_name == 'push' }}
       run: |
-        cd docs
+        cd mkdocs
         mike deploy dev --push
     - name: Build and deploy the lastest documentation upon new release
       if: ${{ github.event_name == 'release' }}
       run: |
-        cd docs
+        cd mkdocs
         mike deploy ${{ github.event.release.name }} latest -u --push

.gitignore

@@ -1,5 +1,6 @@
 # Project specific
-/docs/site/*
+/mkdocs/site/*
+/mkdocs/docs/tutorial/*
 **/.DS_Store
 
 # Byte-compiled / optimized / DLL files

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -1,21 +1,9 @@
 # Documentation
 
-The documentation is available at: <https://jaxleyverse.github.io/jaxley/>
-
-## Building the Documentation
-
-You can build the docs locally by running the following command from this subfolder:
-
-```bash
-jupyter nbconvert --to markdown ../tutorials/*.ipynb --output-dir docs/tutorial/
-jupyter nbconvert --to markdown ../examples/*.ipynb --output-dir docs/examples/
-mkdocs serve
+To build the sphinx documentation, run
 ```
-
-The docs can be updated to GitHub using:
-
-```bash
-jupyter nbconvert --to markdown ../tutorials/*.ipynb --output-dir docs/tutorial/
-jupyter nbconvert --to markdown ../examples/*.ipynb --output-dir docs/examples/
-mkdocs gh-deploy
+make html
+cd _build/html
+python -m http.server
 ```
+This will find all jupyter notebooks, run them, collect the output, and incorporate them into the documentation.

docs/changelog.md

@@ -0,0 +1,5 @@
+(changelog)=
+# Changelog
+
+```{include} ../CHANGELOG.md
+```

docs/code_of_conduct.md

@@ -0,0 +1,2 @@
+```{include} ../CODE_OF_CONDUCT.md
+```

docs/conf.py

@@ -0,0 +1,104 @@
+# This file is part of Jaxley, a differentiable neuroscience simulator. Jaxley is
+# licensed under the Apache License Version 2.0, see <https://www.apache.org/licenses/>
+
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Jaxley'
+copyright = '2024, Jaxleyverse team'
+author = 'Jaxleyverse team'
+
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx_math_dollar",
+    "sphinx.ext.mathjax",
+    'sphinx_rtd_size',
+    "myst_nb",
+]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "jax": ("https://jax.readthedocs.io/en/latest", None),
+}
+
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.myst': 'myst-nb',
+    '.ipynb': 'myst-nb'
+}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# Myst-NB
+myst_enable_extensions = [
+    "dollarmath",
+    "amsmath",
+    "deflist",
+    "colon_fence",
+]
+nb_execution_timeout = 600
+nb_execution_mode = "cache"
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+#
+html_title = ""
+html_logo = "logo.png"
+html_theme = 'sphinx_book_theme'  # sphinx_rtd_theme, sphinx_book_theme
+html_theme_options = {
+    'repository_url': 'https://github.com/jaxleyverse/jaxley',
+    "use_repository_button": True,
+    "use_download_button": False,
+    'repository_branch': 'main',
+    "path_to_docs": 'docs',
+    'launch_buttons': {
+        'colab_url': 'https://colab.research.google.com',
+        'binderhub_url': 'https://mybinder.org'
+    },
+    "toc_title": "Navigation",
+    "show_navbar_depth": 1,
+    "show_toc_level": 3,
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+html_css_files = ['custom.css']
+
+autosummary_generate = True
+autodoc_typehints = "description"
+add_module_names = False
+autodoc_member_order = "bysource"

docs/contributing.md

@@ -0,0 +1,5 @@
+(contributing)=
+# Contributing
+
+```{include} ../CONTRIBUTING.md
+```

docs/contributor_guide.rst

@@ -0,0 +1,16 @@
+.. _contributor-guide:
+
+Developer notes
+===============
+
+`Jaxley` welcomes contributions from the community.
+These are guides to get set up as a developer, as well as
+developer-focused resources.
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contribution guides
+
+   contributing
+   code_of_conduct

docs/credits.md

@@ -0,0 +1,20 @@
+(credits)=
+# Credits
+
+`Jaxley` is a collaborative project between the groups of Jakob Macke (Uni Tübingen), Pedro Gonçalves (KU Leuven / NERF), and Philipp Berens (Uni Tübingen).
+
+## License
+
+`Jaxley` is licensed under the [Apache License Version 2.0 (Apache-2.0)](https://github.com/jaxleyverse/jaxley/blob/main/LICENSE) and
+
+> Copyright (C) 2024 Michael Deistler, Jakob H. Macke, Pedro J. Goncalves, Philipp Berens.
+
+
+## Important dependencies and prior art
+
+* We greatly benefited from previous toolboxes for simulating multicompartment neurons, in particular [NEURON](https://github.com/neuronsimulator/nrn).
+
+
+## Funding
+
+This work was supported by the German Research Foundation (DFG) through Germany's Excellence Strategy (EXC 2064 – Project number 390727645) and the CRC 1233 "Robust Vision", the German Federal Ministry of Education and Research (Tübingen AI Center, FKZ: 01IS18039A), the 'Certification and Foundations of Safe Machine Learning Systems in Healthcare' project funded by the Carl Zeiss Foundation, and the European Union (ERC, "DeepCoMechTome", ref. 101089288, "NextMechMod", ref. 101039115).

docs/faq.rst

@@ -0,0 +1,11 @@
+.. _faq:
+
+FAQ
+=========
+
+.. toctree::
+   :maxdepth: 1
+
+   faq/question_01
+   faq/question_02
+   faq/question_03

docs/faq/question_01.md

@@ -0,0 +1,3 @@
+# What units does Jaxley use?
+
+`Jaxley` uses the same units as the `NEURON` simulator, which are listed [here](https://www.neuron.yale.edu/neuron/static/docs/units/unitchart.html).

docs/faq/question_03.md

@@ -0,0 +1,17 @@
+# What kinds of models can be implemented in Jaxley?
+
+`Jaxley` focuses on biophysical, Hodgkin-Huxley-type models. You can think of `Jaxley` like [the `NEURON` simulator](https://neuron.yale.edu/neuron/) written in `JAX`.
+
+`Jaxley` allows to simulate the following types of models, as well as networks thereof:
+
+- single-compartment (point neuron) Hodgkin-Huxley models
+- multi-compartment Hodgkin-Huxley models
+- rate-based neuron models
+
+For all of these models, `Jaxley` is flexible and accurate. For example, it can flexibly [add new channel models](https://jaxleyverse.github.io/jaxley/tutorial/05_channel_and_synapse_models/), use [different kinds of synapses (conductance-based, tanh, ...)](https://github.com/jaxleyverse/jaxley/tree/main/jaxley/synapses), and it can [insert different kinds of channels in different branches](https://jaxleyverse.github.io/jaxley/tutorial/01_morph_neurons/) (or compartments) within single cells. Like `NEURON`, `Jaxley` implements a backward-Euler solver for stable numerical solution of multi-compartment neurons.
+
+However, `Jaxley` does **not** implement the following types of models:
+
+- leaky-integrate and fire neurons
+- Ishikevich neuron models
+- etc...

docs/index.rst

@@ -0,0 +1,118 @@
+.. Jaxley documentation master file, created by
+   sphinx-quickstart on Tue Oct 18 10:21:12 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+
+Welcome to Jaxley!
+===================
+
+``Jaxley`` is a differentiable simulator for biophysical neuron models in `JAX <https://github.com/google/jax>`_. Its key features are:
+
+- automatic differentiation, allowing gradient-based optimization of thousands of parameters  
+- support for CPU, GPU, or TPU without any changes to the code  
+- ``jit``-compilation, making it as fast as other packages while being fully written in python  
+- backward-Euler solver for stable numerical solution of multicompartment neurons  
+- elegant mechanisms for parameter sharing
+
+
+Getting started
+---------------
+
+``Jaxley`` allows to simulate biophysical neuron models on CPU, GPU, or TPU:
+
+.. code-block:: python
+
+   import matplotlib.pyplot as plt
+   from jax import config
+
+   import jaxley as jx
+   from jaxley.channels import HH
+
+   config.update("jax_platform_name", "cpu")  # Or "gpu" / "tpu".
+
+   cell = jx.Cell()  # Define cell.
+   cell.insert(HH())  # Insert channels.
+
+   current = jx.step_current(i_delay=1.0, i_dur=1.0, i_amp=0.1, delta_t=0.025, t_max=10.0)
+   cell.stimulate(current)  # Stimulate with step current.
+   cell.record("v")  # Record voltage.
+
+   v = jx.integrate(cell)  # Run simulation.
+   plt.plot(v.T)  # Plot voltage trace.
+
+
+If you want to learn more, we have tutorials on how to:
+
+- `simulate morphologically detailed neurons <notebooks/tutorials/01_morph_neurons.html>`_
+- `simulate networks of such neurons <notebooks/tutorials/02_small_network.html>`_
+- `set parameters of cells and networks <notebooks/tutorials/03_setting_parameters.html>`_
+- `speed up simulations with GPUs and jit <notebooks/tutorials/04_jit_and_vmap.html>`_
+- `define your own channels and synapses <notebooks/tutorials/05_channel_and_synapse_models.html>`_
+- `define groups <notebooks/tutorials/06_groups.html>`_
+- `read and handle SWC files <notebooks/tutorials/08_importing_morphologies.html>`_
+- `compute the gradient and train biophysical models <notebooks/tutorials/07_gradient_descent.html>`_
+
+
+
+Installation
+------------
+
+``Jaxley`` is available on `PyPI <https://pypi.org/project/jaxley/>`_:
+
+.. code-block:: console
+
+   pip install jaxley
+
+This will install ``Jaxley`` with CPU support. If you want GPU support, follow the instructions on the `JAX github repository <https://github.com/google/jax>`_ to install `JAX` with GPU support (in addition to installing ``Jaxley``). For example, for NVIDIA GPUs, run
+
+.. code-block:: console
+
+   pip install -U "jax[cuda12]"
+
+
+Feedback and Contributions
+--------------------------
+
+We welcome any feedback on how ``Jaxley`` is working for your neuron models and are happy to receive bug reports, pull requests and other feedback (see `contribute <https://github.com/jaxleyverse/jaxley/blob/main/CONTRIBUTING.md>`_). We wish to maintain a positive community, please read our `Code of Conduct <https://github.com/jaxleyverse/jaxley/blob/main/CODE_OF_CONDUCT.md>`_.
+
+
+Citation
+--------
+
+If you use `Jaxley`, consider citing the `corresponding paper <https://www.biorxiv.org/content/10.1101/2024.08.21.608979>`_:
+
+.. code-block:: console
+   
+   @article{deistler2024differentiable,
+      doi = {10.1101/2024.08.21.608979},
+      year = {2024},
+      publisher = {Cold Spring Harbor Laboratory},
+      author = {Deistler, Michael and Kadhim, Kyra L. and Pals, Matthijs and Beck, Jonas and Huang, Ziwei and Gloeckler, Manuel and Lappalainen, Janne K. and Schr{\"o}der, Cornelius and Berens, Philipp and Gon{\c c}alves, Pedro J. and Macke, Jakob H.},
+      title = {Differentiable simulation enables large-scale training of detailed biophysical models of neural dynamics},
+      journal = {bioRxiv}
+   }
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: Getting started
+
+   installation
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   tutorials
+   faq
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+   :caption: More guides/resources
+
+   jaxley
+   contributor_guide
+   changelog
+   credits