chore(paper): permanent links and README intro (#77)

* chore(paper): permanent links and README intro

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

CHANGELOG.md

@@ -30,6 +30,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 + Fixed broken links and added test to check for links.
   [#68](https://github.com/jeertmans/DiffeRT2d/pull/68)
++ Enhanced the documentation homepage.
+  [#77](https://github.com/jeertmans/DiffeRT2d/pull/77)
 
 (v0.3.2)=
 ## [v0.3.2](https://github.com/jeertmans/DiffeRT2d/compare/v0.3.1...v0.3.2)

README.md

@@ -10,6 +10,25 @@
 
 Differentiable Ray Tracing Python Framework for Radio Propagation.
 
+<!-- start description -->
+
+DiffeRT2d is built on top of the
+[JAX](https://github.com/google/jax)
+library to provide a program that is *differentiable everywhere*.
+With that, performing gradient-based optimization, or training
+Machine Learning models with Ray Tracing (RT) becomes straightforward!
+Moreover, the extensive use of the object-oriented paradigm
+facilitates the simulation of complex objects, such as metasurfaces,
+and the use of more advanced path tracing methods.
+
+The objective of this tool is to provide a **simple-to-use** and
+**highly interpretable** RT framework **for researchers** engaged
+in fundamental studies of RT applied to radio propagation,
+or any researcher interested in the various paths radio waves
+can take in a given environment.
+
+<!-- end description -->
+
 > [!IMPORTANT]
 > For 3D scenarios at city-scales,
 > checkout [DiffeRT](https://github.com/jeertmans/DiffeRT).

docs/source/index.md

@@ -6,31 +6,9 @@ og:description: 2D Toolbox for Differentiable Ray Tracing
 # Welcome to DiffeRT2d's documentation
 
 DiffeRT2d is a Python toolbox for 2D differentiable Ray Tracing,
-with a focus on Radio Propagation applications[^1].
-
-[^1]: This means we are mostly interested in simulating paths from
-  one node (transmitter) to another (receiver),
-  i.e., Point-to-Point Ray Tracing.
-  DiffeRT2d is not designed as a highly efficient image renderer, like in computer graphics.
-  A renderer will usually favor a Ray Launching method instead.
-
-The present tool is thoroughly documented, so please have a look at the
-following sections:
-
-```{toctree}
-:titlesonly:
-:maxdepth: 1
-
-quickstart
-examples_gallery/index
-reference/index
-research/index
-jax_and_jaxtyping
-references
-```
-
-If you are interested in contributing to this tool, please checkout the
-[Contributing](contributing/index) section!
+with a focus on Radio Propagation applications, where we are mostly
+interested in simulating paths from one node (transmitter)
+to another (receiver), i.e., Point-to-Point Ray Tracing.
 
 ```{eval-rst}
 .. plot::
@@ -59,6 +37,30 @@ If you are interested in contributing to this tool, please checkout the
     plt.show()  # doctest: +SKIP
 ```
 
+
+```{include} ../../README.md
+:start-after: <!-- start description -->
+:end-before: <!-- end description -->
+```
+
+The present tool is thoroughly documented, so please have a look at the
+following sections:
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
+quickstart
+examples_gallery/index
+reference/index
+research/index
+jax_and_jaxtyping
+references
+```
+
+If you are interested in contributing to this tool, please checkout the
+[Contributing](contributing/index) section!
+
 ```{toctree}
 :caption: Development
 :hidden:

papers/joss/paper.md

@@ -111,7 +111,7 @@ for optimization problems or Equinox [@kidger2021equinox] for Machine Learning (
 # Usage Examples
 
 The documentation contains
-[an example gallery](https://differt2d.readthedocs.io/latest/examples_gallery/),
+[an example gallery](https://web.archive.org/web/20240628154659/https://differt2d.eertmans.be/latest/examples_gallery/),
 as well as numerous other usage examples disseminated throughout the
 application programming interface (API) documentation.
 
@@ -208,21 +208,23 @@ provided by the Optax library, to successfully solve some optimization problem.
 
 ![Illustration of the different iterations converging towards the maximum of the objective function, see [@eertmans2024eucap] for all details.\label{fig:opt}](optimize_steps.pdf){ width="100%" }
 
-The code to reproduce the above results can be obtained here:
-https://github.com/jeertmans/DiffeRT2d/blob/main/papers/joss/plot_optimize_steps.py.
+The code to reproduce the above results can be found in the
+[GitHub repository](https://web.archive.org/web/20240628155050/https://github.com/jeertmans/DiffeRT2d/blob/main/papers/joss/plot_optimize_steps.py).
 
 ## Machine Learning
 
 In [@mlhelsinki],
 presented at a scientific meeting in Helsinki, June 2024,
 as part of the European Cooperation in Science and Technology (COST)
-action [*INTERACT*](https://interactca20120.org/) (CA20120),
+action
+[*INTERACT*](https://web.archive.org/web/20240628155127/https://interactca20120.org/)
+(CA20120),
 we developed an ML model that learns how to sample path candidates
 to accelerate RT in general.
 
 The model and its training were implemented using the DiffeRT2d library,
 and a detailed notebook is available
-[online](https://eertmans.be/r/cost20120-helsinki).
+[online](https://web.archive.org/web/20240628154718/https://differt2d.eertmans.be/latest/notebooks/cost20120_helsinki_model.html).
 
 # Stability and releases