Merge pull request hyperspy#324 from CSSFrancis/supported-formats-vib…

…ility Improve Logical Flow of Documentation
jlaehne · Dec 12, 2024 · 1f15545 · 1f15545
2 parents 623328f + b43231a
commit 1f15545
Show file tree

Hide file tree

Showing 39 changed files with 77 additions and 5 deletions.
diff --git a/doc/conf.py b/doc/conf.py
@@ -40,6 +40,7 @@
     "sphinx.ext.napoleon",
     "sphinxcontrib.towncrier",
     "sphinx_copybutton",
+    "sphinx_design",
 ]
 
 intersphinx_mapping = {

diff --git a/doc/index.rst b/doc/index.rst
@@ -19,9 +19,74 @@ project for multi-dimensional data analysis. As HyperSpy is rooted in the electr
 microscopy community, data formats used by this community are still particularly
 well represented.
 
+
+.. grid:: 2 3 3 3
+  :gutter: 2
+
+  .. grid-item-card::
+    :link: user_guide/install
+    :link-type: doc
+
+    :octicon:`rocket;2em;sd-text-info` Getting Started
+    ^^^
+
+    New to RosettaSciIO or Python? Find information on how to
+    install RosettaSciIO.
+
+  .. grid-item-card::
+    :link: supported_formats/index
+    :link-type: doc
+
+    :octicon:`checklist;2em;sd-text-info` Supported Formats
+    ^^^
+
+    Overview of the different file formats that RosettaSciIO can read
+    from and write to, as well as information on specific options if applicable.
+
+  .. grid-item-card::
+    :link: user_guide/interoperability
+    :link-type: doc
+
+    :octicon:`arrow-switch;2em;sd-text-info` Interoperability
+    ^^^
+
+    Information on scripts and packages that allow opening data saved using
+    RosettaSciIO with third-party programs.
+
+  .. grid-item-card::
+    :link: file_specification/index
+    :link-type: doc
+
+    :octicon:`checklist;2em;sd-text-info` File Specifications
+    ^^^
+
+    Links to or documentation of file specifications for
+    some of the formats supported by RosettaSciIO.
+
+  .. grid-item-card::
+    :link: api/index
+    :link-type: doc
+
+    :octicon:`book;2em;sd-text-info` API Reference
+    ^^^
+
+    Documentation describing how to use RosettaSciIO with other
+    libraries than HyperSpy or for custom implementations using the
+    Application Programming Interface (API).
+
+  .. grid-item-card::
+    :link: contributing
+    :link-type: doc
+
+    :octicon:`code-square;2em;sd-text-info` Contributing
+    ^^^
+
+    Information on how to implement new file plugins or help improve existing ones.
+
+
 RosettaSciIO provides the dataset, its axes and related metadata contained in a
-file in a python dictionary that can be easily handled by other libraries.
-Similarly, it takes a dictionary as input for file writers.
+file in a :ref:`python dictionary <interfacing-api>` that can be easily
+handled by other libraries.
 
 .. note::
 
@@ -66,6 +131,7 @@ Table of contents
 
    user_guide/index
    file_specification/index
+   supported_formats/index
    api/index
    contributing
    changes
diff --git a/...ser_guide/supported_formats/blockfile.rst → doc/supported_formats/blockfile.rst b/...ser_guide/supported_formats/blockfile.rst → doc/supported_formats/blockfile.rst
diff --git a/doc/user_guide/supported_formats/bruker.rst → doc/supported_formats/bruker.rst b/doc/user_guide/supported_formats/bruker.rst → doc/supported_formats/bruker.rst
diff --git a/doc/user_guide/supported_formats/de5.rst → doc/supported_formats/de5.rst b/doc/user_guide/supported_formats/de5.rst → doc/supported_formats/de5.rst
diff --git a/doc/user_guide/supported_formats/delmic.rst → doc/supported_formats/delmic.rst b/doc/user_guide/supported_formats/delmic.rst → doc/supported_formats/delmic.rst
@@ -19,4 +19,4 @@ API functions
 """""""""""""
 
 .. automodule:: rsciio.delmic
-   :members:
+   :members:
diff --git a/doc/user_guide/supported_formats/dens.rst → doc/supported_formats/dens.rst b/doc/user_guide/supported_formats/dens.rst → doc/supported_formats/dens.rst
diff --git a/...e/supported_formats/digitalmicrograph.rst → doc/supported_formats/digitalmicrograph.rst b/...e/supported_formats/digitalmicrograph.rst → doc/supported_formats/digitalmicrograph.rst
diff --git a/...r_guide/supported_formats/digitalsurf.rst → doc/supported_formats/digitalsurf.rst b/...r_guide/supported_formats/digitalsurf.rst → doc/supported_formats/digitalsurf.rst
diff --git a/doc/user_guide/supported_formats/edax.rst → doc/supported_formats/edax.rst b/doc/user_guide/supported_formats/edax.rst → doc/supported_formats/edax.rst
diff --git a/doc/user_guide/supported_formats/emd.rst → doc/supported_formats/emd.rst b/doc/user_guide/supported_formats/emd.rst → doc/supported_formats/emd.rst
diff --git a/doc/user_guide/supported_formats/empad.rst → doc/supported_formats/empad.rst b/doc/user_guide/supported_formats/empad.rst → doc/supported_formats/empad.rst
diff --git a/...ser_guide/supported_formats/hamamatsu.rst → doc/supported_formats/hamamatsu.rst b/...ser_guide/supported_formats/hamamatsu.rst → doc/supported_formats/hamamatsu.rst
diff --git a/doc/user_guide/supported_formats/hspy.rst → doc/supported_formats/hspy.rst b/doc/user_guide/supported_formats/hspy.rst → doc/supported_formats/hspy.rst
diff --git a/doc/user_guide/supported_formats/image.rst → doc/supported_formats/image.rst b/doc/user_guide/supported_formats/image.rst → doc/supported_formats/image.rst
diff --git a/doc/user_guide/supported_formats/index.rst → doc/supported_formats/index.rst b/doc/user_guide/supported_formats/index.rst → doc/supported_formats/index.rst
diff --git a/doc/user_guide/supported_formats/jeol.rst → doc/supported_formats/jeol.rst b/doc/user_guide/supported_formats/jeol.rst → doc/supported_formats/jeol.rst
diff --git a/...ser_guide/supported_formats/jobinyvon.rst → doc/supported_formats/jobinyvon.rst b/...ser_guide/supported_formats/jobinyvon.rst → doc/supported_formats/jobinyvon.rst
diff --git a/doc/user_guide/supported_formats/mrc.rst → doc/supported_formats/mrc.rst b/doc/user_guide/supported_formats/mrc.rst → doc/supported_formats/mrc.rst
diff --git a/doc/user_guide/supported_formats/mrcz.rst → doc/supported_formats/mrcz.rst b/doc/user_guide/supported_formats/mrcz.rst → doc/supported_formats/mrcz.rst
diff --git a/doc/user_guide/supported_formats/msa.rst → doc/supported_formats/msa.rst b/doc/user_guide/supported_formats/msa.rst → doc/supported_formats/msa.rst
diff --git a/doc/user_guide/supported_formats/netcdf.rst → doc/supported_formats/netcdf.rst b/doc/user_guide/supported_formats/netcdf.rst → doc/supported_formats/netcdf.rst
diff --git a/doc/user_guide/supported_formats/nexus.rst → doc/supported_formats/nexus.rst b/doc/user_guide/supported_formats/nexus.rst → doc/supported_formats/nexus.rst
diff --git a/...ser_guide/supported_formats/pantarhei.rst → doc/supported_formats/pantarhei.rst b/...ser_guide/supported_formats/pantarhei.rst → doc/supported_formats/pantarhei.rst
diff --git a/doc/user_guide/supported_formats/phenom.rst → doc/supported_formats/phenom.rst b/doc/user_guide/supported_formats/phenom.rst → doc/supported_formats/phenom.rst
diff --git a/...er_guide/supported_formats/protochips.rst → doc/supported_formats/protochips.rst b/...er_guide/supported_formats/protochips.rst → doc/supported_formats/protochips.rst
diff --git a/...ide/supported_formats/quantumdetector.rst → doc/supported_formats/quantumdetector.rst b/...ide/supported_formats/quantumdetector.rst → doc/supported_formats/quantumdetector.rst
diff --git a/...user_guide/supported_formats/renishaw.rst → doc/supported_formats/renishaw.rst b/...user_guide/supported_formats/renishaw.rst → doc/supported_formats/renishaw.rst
diff --git a/doc/user_guide/supported_formats/ripple.rst → doc/supported_formats/ripple.rst b/doc/user_guide/supported_formats/ripple.rst → doc/supported_formats/ripple.rst
diff --git a/doc/user_guide/supported_formats/semper.rst → doc/supported_formats/semper.rst b/doc/user_guide/supported_formats/semper.rst → doc/supported_formats/semper.rst
diff --git a/...e/supported_formats/supported_formats.rst → doc/supported_formats/supported_formats.rst b/...e/supported_formats/supported_formats.rst → doc/supported_formats/supported_formats.rst
diff --git a/doc/user_guide/supported_formats/tia.rst → doc/supported_formats/tia.rst b/doc/user_guide/supported_formats/tia.rst → doc/supported_formats/tia.rst
diff --git a/doc/user_guide/supported_formats/tiff.rst → doc/supported_formats/tiff.rst b/doc/user_guide/supported_formats/tiff.rst → doc/supported_formats/tiff.rst
diff --git a/...user_guide/supported_formats/trivista.rst → doc/supported_formats/trivista.rst b/...user_guide/supported_formats/trivista.rst → doc/supported_formats/trivista.rst
diff --git a/doc/user_guide/supported_formats/tvips.rst → doc/supported_formats/tvips.rst b/doc/user_guide/supported_formats/tvips.rst → doc/supported_formats/tvips.rst
diff --git a/doc/user_guide/supported_formats/usid.rst → doc/supported_formats/usid.rst b/doc/user_guide/supported_formats/usid.rst → doc/supported_formats/usid.rst
diff --git a/doc/user_guide/supported_formats/zspy.rst → doc/supported_formats/zspy.rst b/doc/user_guide/supported_formats/zspy.rst → doc/supported_formats/zspy.rst
diff --git a/doc/user_guide/index.rst b/doc/user_guide/index.rst
@@ -3,9 +3,13 @@
 User Guide
 ==========
 
+Welcome to the RosettaSciIO user guide.  This includes information on how to install RosettaSciIO, and
+how to use RosettaSciIO with other libraries than HyperSpy/ with other languages than python.
+
+A list of all the supported file formats can be found in the :ref:`supported formats <supported-formats>` section.
+
 .. toctree::
    :maxdepth: 2
 
    install
-   supported_formats/index
-   interoperability
+   interoperability
diff --git a/pyproject.toml b/pyproject.toml
@@ -119,6 +119,7 @@ doc = [
   "sphinx-copybutton",
   # unpin when sphinxcontrib-towncrier supports towncrier >=24
   "towncrier<24",
+  "sphinx_design",
 ]
 all = [
   "rosettasciio[blockfile]",