Fix docs landing page

docs/faq.rst

@@ -32,15 +32,15 @@ Help! My data is anisotropic!
 
 Various places in the ``riesling`` code used to make assumptions that both the matrix- and voxel-sizes were isotropic. These assumptions have mostly been removed and anisotropic data can be reconstructed quite happily.
 
-A potential difficulty is that by default ``riesling`` will work with a 256 mm isotropic field of view during iterations, before cropping to the nominal field of view at the end. If one dimension of the nominal field of view is too small, ``riesling`` will not be able to create sensitivity maps large enough. The simplest way to fix this is to specify a suitable size with the ``--sense-fov=x,y,z`` option, where the units ``x,y,z`` match the units of the voxel size in the header (usually mm). An alternative is to increase the oversampling beyond 2, but you should check your data actually supports higher oversampling first.
+A potential difficulty is that by default ``riesling`` will work with a 256 mm isotropic field of view during iterations, before cropping to the nominal field of view at the end. If one dimension of the nominal field of view is too small, ``riesling`` will not be able to create sensitivity maps large enough. The simplest way to fix this is to specify a suitable size with the ``--sense-fov=x,y,z`` option, where the units ``x,y,z`` match the units of the voxel size in the header (usually mm). Setting any of ``x,y,z`` to 0 will use the nominal FOV. An alternative is to increase the oversampling beyond 2, but you should check your data actually supports higher oversampling first.
 
 
 What if I have Cartesian data?
 ------------------------------
 
-The default gridding options in ``riesling`` were picked for non-cartesian data and likely will not work with a cartesian dataset. In particular, a twice over-sampled grid is used and the FOV during iterations (determined by `--sense-fov``) is expanded to 256 mm on the basis that most non-cartesian acquisitions oversample the center of k-space and so in practice acquire signal from outside the nominal FOV. These settings will cause artefacts during an iterative recon with cartesian data.
+The default gridding options in ``riesling`` were picked for non-cartesian data and likely will not work with a cartesian dataset. In particular, a twice over-sampled grid is used and the FOV during iterations (determined by ``--sense-fov``) is expanded to 256 mm on the basis that most non-cartesian acquisitions oversample the center of k-space and so in practice acquire signal from outside the nominal FOV. These settings will cause artefacts during an iterative recon with cartesian data.
 
-Adding ``--sense-fov=0,0,0`` will instead crop the sensitivity maps tightly the FOV. I then recommend addding either ``--osamp=1.3`` or ``--osamp=1 --kernel=NN``. The latter will effectively switch off the NUFFT functionality and run a plain FFT instead.
+Adding ``--sense-fov=0,0,0`` will instead crop the sensitivity maps to the nominal FOV. I then recommend addding either ``--osamp=1.3`` or ``--osamp=1 --kernel=NN``. The latter will effectively switch off the NUFFT functionality and run a plain FFT.
 
 Which regularizer should I pick with ADMM?
 ------------------------------------------

docs/index.rst

@@ -3,23 +3,41 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to RIESLING!
-====================================
+RIESLING
+========
 
-.. image:: riesling-logo.png
+.. image:: ../riesling-logo.png
    :alt: RIESLING Logo
 
-RIESLING is a reconstruction toolbox tuned for 3D radial MRI - the name stands for Radial Interstices Enable Speedy Low-volume imagING - but it can process other trajectories as well.
+Radial Interstices Enable Speedy Low-volume imagING (RIESLING) is a tool for reconstructing non-cartesian MRI scans. It was developed for reconstructing 3D radial center-out trajectories associated with Zero Echo-Time (ZTE) or Ultrashort Echo-Time (UTE) sequences. These trajectories provide unique challenges in efficient reconstruction compared to Cartesian trajectories (both 2D and 3D). However it is capable of reconstructing any trajectory.
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+   :maxdepth: 1
+   :caption: Contents
 
-   contents
+   faq
+   data
+   recon
+   util
+   op
 
-Indices and tables
-==================
+Commands
+--------
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+RIESLING is provided as a single executable file, similar to ``bart``. The ``riesling`` executable provides multiple individual commands, which vary from basic utilities to interrogate files to complete reconstruction pipelines. To see a full list of commands currently available, run ``riesling``. Detailed help for each command can be found in the category pages: :doc:`util`, :doc:`op`, and :doc:`recon`. The full list is not repeated here as they are subject to change. However, the most useful are:
+
+- ``riesling h5`` Prints information about compatible ``.h5`` files
+- ``riesling rss`` Performs the most basic reconstruction possible
+- ``riesling admm`` Regularized least-squares reconstruction, similar to ``bart pics``. *You probably want this one*.
+
+RIESLING exploits the inherent oversampling of most non-Cartesian trajectories at the center of k-space to generate SENSE maps directly from the input data, but utilities are provided to explicitly extract sensitivities if desired. Further details can be found in :doc:`util`. Internally, similarly to BART, RIESLING pipelines are constructed as a series of Linear Operators. These operators are exposed as individual commands if you wish to build up your own pipeline, see :doc:`op`.
+
+Examples
+--------
+
+A `tutorial notebook <https://github.com/spinicist/riesling-examples/tutorial.ipynb>`_ can be run interactively at on `MyBinder <https://mybinder.org/v2/gh/spinicist/riesling-examples/HEAD?filepath=tutorial.ipynb>`_. This explains the various steps required to generate a simulated phantom dataset and then reconstruct it.
+
+Input Data
+----------
+
+An important step with using RIESLING is providing data in the correct ``.h5`` format. Details of this format can be found in :doc:`data`. Matlab code to generate these files is provided in the ``/matlab`` directory of the repository. Users of the ZTE sequence on GE platforms should contact the authors to discuss conversion strategies.