From 32c87a414d97d130b012cae4750ebb90fc388fa5 Mon Sep 17 00:00:00 2001 From: Carter Francis Date: Mon, 21 Oct 2024 15:32:44 -0500 Subject: [PATCH 1/6] Doc: Add Grid to Front page --- doc/conf.py | 1 + doc/index.rst | 60 ++++++++++++++++++++++++++++++++++++++++ doc/user_guide/index.rst | 3 ++ pyproject.toml | 1 + 4 files changed, 65 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index f56e99b6d..174d9fd43 100644 --- 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 index 67d3c9dfa..635b64e3e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -19,6 +19,66 @@ 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? The getting started guide provides an + introduction on basic usage of rosettasciio and how to install it. + + .. grid-item-card:: + :link: user_guide/supported_formats + :link-type: doc + + :octicon:`checklist;2em;sd-text-info` Supported Formats + ^^^ + + This provides a nice overview of the different files that can be read and written by rosettasciio. + + .. grid-item-card:: + :link: user_guide/interoperability + :link-type: doc + + :octicon:`arrow-switch;2em;sd-text-info` Interoperability + ^^^ + + Documentation describing how to use rosettasciio with other libraries than HyperSpy. + + .. grid-item-card:: + :link: file_specification/index + :link-type: doc + + :octicon:`checklist;2em;sd-text-info` File Specifications + ^^^ + + Links to File Specifications for the different file formats supported by rosettasciio. + + .. grid-item-card:: + :link: api/index + :link-type: doc + + :octicon:`book;2em;sd-text-info` API Reference + ^^^ + + Documentation of 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 contribute to the development of rosettasciio. + + 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. diff --git a/doc/user_guide/index.rst b/doc/user_guide/index.rst index 3cc9bc088..be6867389 100644 --- a/doc/user_guide/index.rst +++ b/doc/user_guide/index.rst @@ -3,6 +3,9 @@ User Guide ========== +Welcome to the RosettaSciIO user guide. This guide provides in-depth information on key concepts of RosettaSciIO +and how to use it along with background information and explanations. + .. toctree:: :maxdepth: 2 diff --git a/pyproject.toml b/pyproject.toml index 2025b7780..9b6493a51 100644 --- 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]", From 2ebacc0b435bc4385b9481508c10910dac24fb52 Mon Sep 17 00:00:00 2001 From: Carter Francis Date: Mon, 21 Oct 2024 17:16:57 -0500 Subject: [PATCH 2/6] Doc: Add Blurb describing the User Guide. --- doc/user_guide/index.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/user_guide/index.rst b/doc/user_guide/index.rst index be6867389..39de1b10e 100644 --- a/doc/user_guide/index.rst +++ b/doc/user_guide/index.rst @@ -4,7 +4,8 @@ User Guide ========== Welcome to the RosettaSciIO user guide. This guide provides in-depth information on key concepts of RosettaSciIO -and how to use it along with background information and explanations. +and how to use it. This includes information on how to install RosettaSciIO, the supported file formats, and +how to use RosettaSciIO with other libraries than HyperSpy/ with other languages than python. .. toctree:: :maxdepth: 2 From 9d0da89df7693914cbf9c60f17f261113ae93dfb Mon Sep 17 00:00:00 2001 From: Carter Francis Date: Mon, 21 Oct 2024 17:26:09 -0500 Subject: [PATCH 3/6] Doc: Fix link to supported formats --- doc/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/index.rst b/doc/index.rst index 635b64e3e..e3a447654 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -34,7 +34,7 @@ well represented. introduction on basic usage of rosettasciio and how to install it. .. grid-item-card:: - :link: user_guide/supported_formats + :link: user_guide/supported_formats/index :link-type: doc :octicon:`checklist;2em;sd-text-info` Supported Formats From 0bcacc78c8e6253e515534d9e14a62a08fc60fc1 Mon Sep 17 00:00:00 2001 From: Carter Francis Date: Mon, 28 Oct 2024 14:01:06 -0500 Subject: [PATCH 4/6] Doc: Refactor Documentation to make supported formats a top level par tof the documentation. --- doc/index.rst | 26 ++++++++++++------- .../supported_formats/blockfile.rst | 0 .../supported_formats/bruker.rst | 0 .../supported_formats/de5.rst | 0 doc/supported_formats/delmic.rst | 0 .../supported_formats/dens.rst | 0 .../supported_formats/digitalmicrograph.rst | 0 .../supported_formats/digitalsurf.rst | 0 .../supported_formats/edax.rst | 0 .../supported_formats/emd.rst | 0 .../supported_formats/empad.rst | 0 .../supported_formats/hamamatsu.rst | 0 .../supported_formats/hspy.rst | 0 .../supported_formats/image.rst | 0 .../supported_formats/index.rst | 0 .../supported_formats/jeol.rst | 0 .../supported_formats/jobinyvon.rst | 0 .../supported_formats/mrc.rst | 0 .../supported_formats/mrcz.rst | 0 .../supported_formats/msa.rst | 0 .../supported_formats/netcdf.rst | 0 .../supported_formats/nexus.rst | 0 .../supported_formats/pantarhei.rst | 0 .../supported_formats/phenom.rst | 0 .../supported_formats/protochips.rst | 0 .../supported_formats/quantumdetector.rst | 0 .../supported_formats/renishaw.rst | 0 .../supported_formats/ripple.rst | 0 .../supported_formats/semper.rst | 0 .../supported_formats/supported_formats.rst | 0 .../supported_formats/tia.rst | 0 .../supported_formats/tiff.rst | 0 .../supported_formats/trivista.rst | 0 .../supported_formats/tvips.rst | 0 .../supported_formats/usid.rst | 0 .../supported_formats/zspy.rst | 0 doc/user_guide/index.rst | 5 ++-- doc/user_guide/supported_formats/delmic.rst | 22 ---------------- 38 files changed, 19 insertions(+), 34 deletions(-) rename doc/{user_guide => }/supported_formats/blockfile.rst (100%) rename doc/{user_guide => }/supported_formats/bruker.rst (100%) rename doc/{user_guide => }/supported_formats/de5.rst (100%) create mode 100644 doc/supported_formats/delmic.rst rename doc/{user_guide => }/supported_formats/dens.rst (100%) rename doc/{user_guide => }/supported_formats/digitalmicrograph.rst (100%) rename doc/{user_guide => }/supported_formats/digitalsurf.rst (100%) rename doc/{user_guide => }/supported_formats/edax.rst (100%) rename doc/{user_guide => }/supported_formats/emd.rst (100%) rename doc/{user_guide => }/supported_formats/empad.rst (100%) rename doc/{user_guide => }/supported_formats/hamamatsu.rst (100%) rename doc/{user_guide => }/supported_formats/hspy.rst (100%) rename doc/{user_guide => }/supported_formats/image.rst (100%) rename doc/{user_guide => }/supported_formats/index.rst (100%) rename doc/{user_guide => }/supported_formats/jeol.rst (100%) rename doc/{user_guide => }/supported_formats/jobinyvon.rst (100%) rename doc/{user_guide => }/supported_formats/mrc.rst (100%) rename doc/{user_guide => }/supported_formats/mrcz.rst (100%) rename doc/{user_guide => }/supported_formats/msa.rst (100%) rename doc/{user_guide => }/supported_formats/netcdf.rst (100%) rename doc/{user_guide => }/supported_formats/nexus.rst (100%) rename doc/{user_guide => }/supported_formats/pantarhei.rst (100%) rename doc/{user_guide => }/supported_formats/phenom.rst (100%) rename doc/{user_guide => }/supported_formats/protochips.rst (100%) rename doc/{user_guide => }/supported_formats/quantumdetector.rst (100%) rename doc/{user_guide => }/supported_formats/renishaw.rst (100%) rename doc/{user_guide => }/supported_formats/ripple.rst (100%) rename doc/{user_guide => }/supported_formats/semper.rst (100%) rename doc/{user_guide => }/supported_formats/supported_formats.rst (100%) rename doc/{user_guide => }/supported_formats/tia.rst (100%) rename doc/{user_guide => }/supported_formats/tiff.rst (100%) rename doc/{user_guide => }/supported_formats/trivista.rst (100%) rename doc/{user_guide => }/supported_formats/tvips.rst (100%) rename doc/{user_guide => }/supported_formats/usid.rst (100%) rename doc/{user_guide => }/supported_formats/zspy.rst (100%) delete mode 100644 doc/user_guide/supported_formats/delmic.rst diff --git a/doc/index.rst b/doc/index.rst index e3a447654..369cb82b7 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -30,17 +30,18 @@ well represented. :octicon:`rocket;2em;sd-text-info` Getting Started ^^^ - New to rosettasciio or Python? The getting started guide provides an - introduction on basic usage of rosettasciio and how to install it. + New to RosettaSciIO or Python? Find information on how to + install RosettaSciIO. .. grid-item-card:: - :link: user_guide/supported_formats/index + :link: supported_formats/index :link-type: doc :octicon:`checklist;2em;sd-text-info` Supported Formats ^^^ - This provides a nice overview of the different files that can be read and written by rosettasciio. + 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 @@ -49,7 +50,8 @@ well represented. :octicon:`arrow-switch;2em;sd-text-info` Interoperability ^^^ - Documentation describing how to use rosettasciio with other libraries than HyperSpy. + Information on scripts and packages that allow opening data saved using + RosettaSciIO with third-party programs. .. grid-item-card:: :link: file_specification/index @@ -58,7 +60,8 @@ well represented. :octicon:`checklist;2em;sd-text-info` File Specifications ^^^ - Links to File Specifications for the different file formats supported by rosettasciio. + Links to or documentation of file specifications for + some of the formats supported by RosettaSciIO. .. grid-item-card:: :link: api/index @@ -67,7 +70,9 @@ well represented. :octicon:`book;2em;sd-text-info` API Reference ^^^ - Documentation of the Application Programming Interface (API), + 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 @@ -76,12 +81,12 @@ well represented. :octicon:`code-square;2em;sd-text-info` Contributing ^^^ - Information on how to contribute to the development of rosettasciio. + 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 ` that can be easily +handled by other libraries. .. note:: @@ -126,6 +131,7 @@ Table of contents user_guide/index file_specification/index + supported_formats/index api/index contributing changes diff --git a/doc/user_guide/supported_formats/blockfile.rst b/doc/supported_formats/blockfile.rst similarity index 100% rename from doc/user_guide/supported_formats/blockfile.rst rename to doc/supported_formats/blockfile.rst diff --git a/doc/user_guide/supported_formats/bruker.rst b/doc/supported_formats/bruker.rst similarity index 100% rename from doc/user_guide/supported_formats/bruker.rst rename to doc/supported_formats/bruker.rst diff --git a/doc/user_guide/supported_formats/de5.rst b/doc/supported_formats/de5.rst similarity index 100% rename from doc/user_guide/supported_formats/de5.rst rename to doc/supported_formats/de5.rst diff --git a/doc/supported_formats/delmic.rst b/doc/supported_formats/delmic.rst new file mode 100644 index 000000000..e69de29bb diff --git a/doc/user_guide/supported_formats/dens.rst b/doc/supported_formats/dens.rst similarity index 100% rename from doc/user_guide/supported_formats/dens.rst rename to doc/supported_formats/dens.rst diff --git a/doc/user_guide/supported_formats/digitalmicrograph.rst b/doc/supported_formats/digitalmicrograph.rst similarity index 100% rename from doc/user_guide/supported_formats/digitalmicrograph.rst rename to doc/supported_formats/digitalmicrograph.rst diff --git a/doc/user_guide/supported_formats/digitalsurf.rst b/doc/supported_formats/digitalsurf.rst similarity index 100% rename from doc/user_guide/supported_formats/digitalsurf.rst rename to doc/supported_formats/digitalsurf.rst diff --git a/doc/user_guide/supported_formats/edax.rst b/doc/supported_formats/edax.rst similarity index 100% rename from doc/user_guide/supported_formats/edax.rst rename to doc/supported_formats/edax.rst diff --git a/doc/user_guide/supported_formats/emd.rst b/doc/supported_formats/emd.rst similarity index 100% rename from doc/user_guide/supported_formats/emd.rst rename to doc/supported_formats/emd.rst diff --git a/doc/user_guide/supported_formats/empad.rst b/doc/supported_formats/empad.rst similarity index 100% rename from doc/user_guide/supported_formats/empad.rst rename to doc/supported_formats/empad.rst diff --git a/doc/user_guide/supported_formats/hamamatsu.rst b/doc/supported_formats/hamamatsu.rst similarity index 100% rename from doc/user_guide/supported_formats/hamamatsu.rst rename to doc/supported_formats/hamamatsu.rst diff --git a/doc/user_guide/supported_formats/hspy.rst b/doc/supported_formats/hspy.rst similarity index 100% rename from doc/user_guide/supported_formats/hspy.rst rename to doc/supported_formats/hspy.rst diff --git a/doc/user_guide/supported_formats/image.rst b/doc/supported_formats/image.rst similarity index 100% rename from doc/user_guide/supported_formats/image.rst rename to doc/supported_formats/image.rst diff --git a/doc/user_guide/supported_formats/index.rst b/doc/supported_formats/index.rst similarity index 100% rename from doc/user_guide/supported_formats/index.rst rename to doc/supported_formats/index.rst diff --git a/doc/user_guide/supported_formats/jeol.rst b/doc/supported_formats/jeol.rst similarity index 100% rename from doc/user_guide/supported_formats/jeol.rst rename to doc/supported_formats/jeol.rst diff --git a/doc/user_guide/supported_formats/jobinyvon.rst b/doc/supported_formats/jobinyvon.rst similarity index 100% rename from doc/user_guide/supported_formats/jobinyvon.rst rename to doc/supported_formats/jobinyvon.rst diff --git a/doc/user_guide/supported_formats/mrc.rst b/doc/supported_formats/mrc.rst similarity index 100% rename from doc/user_guide/supported_formats/mrc.rst rename to doc/supported_formats/mrc.rst diff --git a/doc/user_guide/supported_formats/mrcz.rst b/doc/supported_formats/mrcz.rst similarity index 100% rename from doc/user_guide/supported_formats/mrcz.rst rename to doc/supported_formats/mrcz.rst diff --git a/doc/user_guide/supported_formats/msa.rst b/doc/supported_formats/msa.rst similarity index 100% rename from doc/user_guide/supported_formats/msa.rst rename to doc/supported_formats/msa.rst diff --git a/doc/user_guide/supported_formats/netcdf.rst b/doc/supported_formats/netcdf.rst similarity index 100% rename from doc/user_guide/supported_formats/netcdf.rst rename to doc/supported_formats/netcdf.rst diff --git a/doc/user_guide/supported_formats/nexus.rst b/doc/supported_formats/nexus.rst similarity index 100% rename from doc/user_guide/supported_formats/nexus.rst rename to doc/supported_formats/nexus.rst diff --git a/doc/user_guide/supported_formats/pantarhei.rst b/doc/supported_formats/pantarhei.rst similarity index 100% rename from doc/user_guide/supported_formats/pantarhei.rst rename to doc/supported_formats/pantarhei.rst diff --git a/doc/user_guide/supported_formats/phenom.rst b/doc/supported_formats/phenom.rst similarity index 100% rename from doc/user_guide/supported_formats/phenom.rst rename to doc/supported_formats/phenom.rst diff --git a/doc/user_guide/supported_formats/protochips.rst b/doc/supported_formats/protochips.rst similarity index 100% rename from doc/user_guide/supported_formats/protochips.rst rename to doc/supported_formats/protochips.rst diff --git a/doc/user_guide/supported_formats/quantumdetector.rst b/doc/supported_formats/quantumdetector.rst similarity index 100% rename from doc/user_guide/supported_formats/quantumdetector.rst rename to doc/supported_formats/quantumdetector.rst diff --git a/doc/user_guide/supported_formats/renishaw.rst b/doc/supported_formats/renishaw.rst similarity index 100% rename from doc/user_guide/supported_formats/renishaw.rst rename to doc/supported_formats/renishaw.rst diff --git a/doc/user_guide/supported_formats/ripple.rst b/doc/supported_formats/ripple.rst similarity index 100% rename from doc/user_guide/supported_formats/ripple.rst rename to doc/supported_formats/ripple.rst diff --git a/doc/user_guide/supported_formats/semper.rst b/doc/supported_formats/semper.rst similarity index 100% rename from doc/user_guide/supported_formats/semper.rst rename to doc/supported_formats/semper.rst diff --git a/doc/user_guide/supported_formats/supported_formats.rst b/doc/supported_formats/supported_formats.rst similarity index 100% rename from doc/user_guide/supported_formats/supported_formats.rst rename to doc/supported_formats/supported_formats.rst diff --git a/doc/user_guide/supported_formats/tia.rst b/doc/supported_formats/tia.rst similarity index 100% rename from doc/user_guide/supported_formats/tia.rst rename to doc/supported_formats/tia.rst diff --git a/doc/user_guide/supported_formats/tiff.rst b/doc/supported_formats/tiff.rst similarity index 100% rename from doc/user_guide/supported_formats/tiff.rst rename to doc/supported_formats/tiff.rst diff --git a/doc/user_guide/supported_formats/trivista.rst b/doc/supported_formats/trivista.rst similarity index 100% rename from doc/user_guide/supported_formats/trivista.rst rename to doc/supported_formats/trivista.rst diff --git a/doc/user_guide/supported_formats/tvips.rst b/doc/supported_formats/tvips.rst similarity index 100% rename from doc/user_guide/supported_formats/tvips.rst rename to doc/supported_formats/tvips.rst diff --git a/doc/user_guide/supported_formats/usid.rst b/doc/supported_formats/usid.rst similarity index 100% rename from doc/user_guide/supported_formats/usid.rst rename to doc/supported_formats/usid.rst diff --git a/doc/user_guide/supported_formats/zspy.rst b/doc/supported_formats/zspy.rst similarity index 100% rename from doc/user_guide/supported_formats/zspy.rst rename to doc/supported_formats/zspy.rst diff --git a/doc/user_guide/index.rst b/doc/user_guide/index.rst index 39de1b10e..3b7ff9861 100644 --- a/doc/user_guide/index.rst +++ b/doc/user_guide/index.rst @@ -11,5 +11,6 @@ how to use RosettaSciIO with other libraries than HyperSpy/ with other languages :maxdepth: 2 install - supported_formats/index - interoperability \ No newline at end of file + interoperability + +.. include:: install.rst diff --git a/doc/user_guide/supported_formats/delmic.rst b/doc/user_guide/supported_formats/delmic.rst deleted file mode 100644 index 60ef92d10..000000000 --- a/doc/user_guide/supported_formats/delmic.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. _delmic-format: - -Delmic HDF5 ------------ - -RosettaScIO can only read hyperspectral cathodoluminescence .h5 datasets from Delmic. The file reading will be implemented step by step for the various Delmic data formats. - -.. Note:: - To read the cathodoluminescence .h5 datasets in `HyperSpy `_, use the - ``reader`` argument to define the correct file plugin as the ``.h5`` - extension is not unique to this reader: - - .. code-block:: python - - >>> import hyperspy.api as hs - >>> hs.load("filename.h5", reader="Delmic") - -API functions -""""""""""""" - -.. automodule:: rsciio.delmic - :members: From a99c41db0c35163e964f30e8ba98504b05efee26 Mon Sep 17 00:00:00 2001 From: Carter Francis Date: Tue, 3 Dec 2024 11:45:02 -0600 Subject: [PATCH 5/6] Doc: Re-add Delimc file details. --- doc/supported_formats/delmic.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/doc/supported_formats/delmic.rst b/doc/supported_formats/delmic.rst index e69de29bb..adea122b3 100644 --- a/doc/supported_formats/delmic.rst +++ b/doc/supported_formats/delmic.rst @@ -0,0 +1,22 @@ +.. _delmic-format: + +Delmic HDF5 +----------- + +RosettaScIO can only read hyperspectral cathodoluminescence .h5 datasets from Delmic. The file reading will be implemented step by step for the various Delmic data formats. + +.. Note:: + To read the cathodoluminescence .h5 datasets in `HyperSpy `_, use the + ``reader`` argument to define the correct file plugin as the ``.h5`` + extension is not unique to this reader: + + .. code-block:: python + + >>> import hyperspy.api as hs + >>> hs.load("filename.h5", reader="Delmic") + +API functions +""""""""""""" + +.. automodule:: rsciio.delmic + :members: \ No newline at end of file From b43231aa1d55f70d8d78019d51cba466174fc4e5 Mon Sep 17 00:00:00 2001 From: Carter Francis Date: Thu, 12 Dec 2024 09:17:57 -0600 Subject: [PATCH 6/6] Refactor: Apply comments from @ericpre --- doc/user_guide/index.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/user_guide/index.rst b/doc/user_guide/index.rst index 3b7ff9861..ad9f22c53 100644 --- a/doc/user_guide/index.rst +++ b/doc/user_guide/index.rst @@ -3,14 +3,13 @@ User Guide ========== -Welcome to the RosettaSciIO user guide. This guide provides in-depth information on key concepts of RosettaSciIO -and how to use it. This includes information on how to install RosettaSciIO, the supported file formats, and +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 ` section. + .. toctree:: :maxdepth: 2 install interoperability - -.. include:: install.rst