chore(docs): improvement overall structure

differt/src/differt/scene/sionna.py

@@ -1,5 +1,5 @@
 """
-Provide a compatibility layer with Sionna's scenes.
+Provide a compatibility layer with Sionna's scenes :cite:`sionna`.
 
 Sionna uses the simple XML-based format from Mitsuba 3.
 """

docs/source/api_reference.rst

@@ -0,0 +1,8 @@
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   reference/differt
+   reference/differt_core

docs/source/guides.rst

@@ -0,0 +1,11 @@
+Guides
+======
+
+.. toctree::
+   :maxdepth: 1
+
+   numpy_vs_jax.md
+   batch_axes.md
+   notebooks/type_checking
+   notebooks/performance_tips
+   notebooks/path_candidates

docs/source/index.rst

@@ -1,27 +1,46 @@
 DiffeRT: Differentiable Ray Tracing Toolbox for Radio Propagation
 =================================================================
 
+DiffeRT is a Python module that aims to make *Differentiable Ray Tracing* accessible
+to researchers in radio propagation!
+
+It is currently developed as part of a PhD, but a lot of work is put into documentating and
+testing the tool, so any researcher should be able to understand how to use this tool for
+their own research.
+
+As mentioned on the GitHub page, the current state of the project is still considered to
+be under *high-development*, and we welcome any contribution!
+
+Contents
+--------
+
 .. toctree::
    :maxdepth: 1
-   :caption: Tutorials
+
+   installation
+
+.. toctree::
+   :caption: Basic Tutorials
+   :maxdepth: 1
 
    notebooks/quickstart
    notebooks/advanced_path_tracing
    notebooks/plotting_backend
    notebooks/diffraction
    notebooks/ray_tracing_at_city_scale
-   notebooks/multipath
 
 .. toctree::
+   :caption: Advanced Tutorials
    :maxdepth: 1
+
+   notebooks/multipath
+
+.. toctree::
    :caption: Reference
+   :maxdepth: 2
 
-   reference/differt
-   reference/differt_core
-   numpy_vs_jax.md
-   batch_axes.md
-   notebooks/type_checking
-   notebooks/performance_tips
-   notebooks/path_candidates
+   API <api_reference>
+   guides
    citing
    references
+   Report an issue <https://github.com/jeertmans/DiffeRT/issues>

docs/source/installation.md

@@ -0,0 +1,60 @@
+# Installation
+
+DiffeRT consists of two Python modules, {mod}`differt` and {mod}`differt_core`,
+where the latter is direct dependency of the former, and both share the *exact same version*.
+
+The main package, {mod}`differt`, uses Python-only code. The core package, {mod}`differt_core`,
+even though only containing a very limited set of utitilies, is written in Rust to offer good performances,
+especially when reading large files or generating path candidates (see {ref}`path_candidates`).
+
+Pre-built binaries are available for most platforms, and we recommend users to install DiffeRT with pip.
+
+## Pip Install
+
+The recommended installation procedure is with pip:
+
+```bash
+pip install differt
+```
+
+:::{important}
+If you encounter an error with installing from pip, e.g.,
+because it is missing pre-built binaries for your platform,
+please report it as
+[an issue in GitHub](https://github.com/jeertmans/DiffeRT/issues)!
+:::
+
+### About JAX
+
+If you want to leverage the power of your GPU(s) or TPU(s), you may want
+to look at [JAX's installation guide](https://github.com/jax-ml/jax?tab=readme-ov-file#installation),
+as they provide the necessary information about how to install JAX with support for your target device.
+
+DiffeRT works seamlessly with JAX regardless of the active devices (i.e, CPU, GPU, or TPU).
+
+### Optional dependencies
+
+By default, DiffeRT will only install a limited set of dependencies, and will not include
+any plotting backend, for example.
+
+You may want to install those optional features by using *extras*[^1]:
+
+- **Plotting backends:**
+  - `matplotlib`: provide Matplotlib plotting backend;
+  - `plotly`: provide Plotly plotting backend;
+  - `vispy`: provide VisPy plotting backend;
+- **VisPy-specific:**
+  - `vispy-backend`: provide a default [backend toolkit for VisPy](https://vispy.org/installation.html);
+- **Jupyter support:**
+  - `jupyter`: provide support for Matplotlib and VisPy interactive plot inside notebooks;
+- **Aliases:**
+  - `all`: alias to `jupyter,matplotlib,plotly,vispy,vispy-backend`;
+
+[^1]: Extras are installed with `pip install "differt[extra_1,extra_2,...]`.
+
+## Install from source
+
+If you consider contributing to DiffeRT (*thanks!*), or you want to on your own
+local version, you will probably need to build the project from source.
+
+TODO.

docs/source/notebooks/multipath.ipynb

@@ -102,7 +102,8 @@
     "Street canyons are probably one of the most common types of scenarios studied in RT,\n",
     "due to their simplicity to model, but also important presence in big cities.\n",
     "\n",
-    "As we provide a compatibility layer with Sionna scenes, we will simply load the `'simple_street_canyon'` scene.\n",
+    "As we provide a compatibility layer with Sionna scenes {cite}`sionna`,\n",
+    "we will simply load the `'simple_street_canyon'` scene.\n",
     "\n",
     "You can download all the scenes from the Sionna repository with\n",
     "{func}`download_sionna_scenes<differt.scene.sionna.download_sionna_scenes>`.\n",
@@ -581850,7 +581851,7 @@
    "version": "3.11.8"
   },
   "mystnb": {
-    "execution_mode": "off"
+   "execution_mode": "off"
   }
  },
  "nbformat": 4,

docs/source/references.bib

@@ -76,6 +76,15 @@ @inproceedings{mpt-eucap2023
   doi       = {10.23919/EuCAP57121.2023.10132934},
 }
 
+@article{sionna,
+  author  = {Hoydis, Jakob and Cammerer, Sebastian and {Ait Aoudia}, Fayçal and Vem, Avinash and Binder, Nikolaus and Marcus, Guillermo and Keller, Alexander},
+  title   = {Sionna: An Open-Source Library for Next-Generation Physical Layer Research},
+  year    = {2022},
+  month   = {mar},
+  journal = {arXiv preprint},
+  online  = {https://arxiv.org/abs/2203.11854},
+}
+
 @book{utd-mcnamara,
   author    = {McNamara, D. and Pistorius, C. and Malherbe, J.},
   title     = {Introduction to the {{Uniform Geometrical Theory}} of {{Diffraction}}},

pyproject.toml

@@ -20,7 +20,7 @@ docs = [
   "myst-nb>=0.17.2",
   "pillow>=10.1.0",
   "sphinx-autodoc-typehints>=1.23",
-  "sphinx-book-theme>=1.0.1",
+  "sphinx-book-theme>=1.1.3",
   "sphinx-copybutton>=0.5.2",
   "sphinx-design>=0.5.0",
   "sphinx-remove-toctrees>=0.0.3",