Merge pull request #27 from jlaehne/doc-update

Add doi, improve doc

README.md

@@ -3,6 +3,7 @@
 [![codecov](https://codecov.io/gh/hyperspy/holospy/graph/badge.svg?token=XB1QDTXQ86)](https://codecov.io/gh/hyperspy/holospy)
 [![Docs](https://readthedocs.org/projects/holospy/badge/?version=latest)](https://holospy.readthedocs.io/en/latest/?badge=latest)
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![DOI](https://zenodo.org/badge/2233998.svg)](https://zenodo.org/badge/latestdoi/2233998)
 
 **HoloSpy** is a Python package extending the functionality for multi-dimensional
 data analysis provided by the [HyperSpy](https://hyperspy.org) library. It is

doc/changes.rst

@@ -1,3 +1,3 @@
-.. This is a stub, see the top level CHANGELOG.rst file for the changelog.
+.. This is a stub, see the top level CHANGES.rst file for the changelog.
 
 .. include:: ../CHANGES.rst

doc/conf.py

@@ -39,6 +39,7 @@
     # numpydoc is necessary to parse the docstring using sphinx
     # otherwise the nitpicky option will raise many warnings
     # "numpydoc",
+    "sphinx_design",
     "sphinx_favicon",
     "sphinx.ext.autodoc",
     "sphinx.ext.githubpages",

doc/index.rst

@@ -1,30 +1,12 @@
-Welcome to HoloSpy's documentation!
-***********************************
-**HoloSpy** is a Python package extending the functionality for multi-dimensional
-data analysis provided by the `HyperSpy <https://hyperspy.org/>`_ library. It is
-aimed at helping with the analysis of (off-axis) electron holography data.
-
-Check out the :ref:`installation` section for further information, including
-how to start using this project.
-
-.. note::
-
-   This is an open-source community project: everyone is welcome to contribute.
-   Please read our (see :ref:`contributing_label`) guidelines and get started!
-
-Contents
-========
-
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   :hidden:
 
    user_guide/index.rst
    api/index.rst
    contributing.rst
    changes.rst
 
 
-.. include:: citing.rst
-
-.. include:: license.rst
+.. include:: intro.rst
 

doc/intro.rst

@@ -0,0 +1,119 @@
+Welcome to HoloSpy's documentation!
+***********************************
+
+**HoloSpy** is a Python package extending the functionality for 
+multi-dimensional data analysis provided by the `HyperSpy 
+<https://hyperspy.org/>`_ library. It is aimed at helping with the analysis of 
+(off-axis) electron holography data. Originally developed as part of `HyperSpy 
+<https://hyperspy.org/>`_, these and other domain specific features have been 
+split out into dedicated packages with the :external+hyperspy:ref:`HyperSpy 2.0 
+release <changes_2.0>`.
+
+Check out the :ref:`installation` section for further information, including
+how to start using this project.
+
+.. note::
+
+   This is an open-source community project: everyone is welcome to contribute.
+   Please read our (see :ref:`contributing_label`) guidelines and get started!
+
+
+Learning resources
+==================
+
+.. grid:: 2 3 3 3
+  :gutter: 2
+
+  .. grid-item-card::
+    :link: user_guide/installation
+    :link-type: doc
+
+    :octicon:`rocket;2em;sd-text-info` Getting Started
+    ^^^
+
+    New to holoSpy or the HyperSpy ecosystem? The getting started guide provides an
+    introduction on basic usage of holoSpy and how to install it.
+
+  .. grid-item-card::
+    :link: user_guide/index
+    :link-type: doc
+
+    :octicon:`book;2em;sd-text-info` User Guide
+    ^^^
+
+    The user guide provides in-depth information on key concepts of holoSpy
+    and how to use it along with background information and explanations.
+
+  .. grid-item-card::
+    :link: api/index
+    :link-type: doc
+
+    :octicon:`code-square;2em;sd-text-info` Reference
+    ^^^
+
+    Documentation of the metadata specification and of the Application Progamming Interface (API),
+    which describe how holoSpy functions work and which parameters can be used.
+
+  .. grid-item-card::
+    :link: https://github.com/hyperspy/holospy-demos
+
+    :octicon:`workflow;2em;sd-text-info` Tutorials
+    ^^^
+
+    Tutorials in form of Jupyter Notebooks to learn how to process
+    off-axis electron holography data using holoSpy.
+
+  .. grid-item-card::
+    :link: contributing
+    :link-type: doc
+
+    :octicon:`people;2em;sd-text-info` Contributing
+    ^^^
+
+    holoSpy and the whole HyperSpy ecosystem are a community project
+    maintained for and by its users. There are many ways you can help!
+
+  .. grid-item-card::
+    :link: changes
+    :link-type: doc
+
+    :octicon:`zap;2em;sd-text-info` Changes
+    ^^^
+
+    To learn about recent changes, check out the release notes.
+
+
+Citing HoloSpy
+==============
+
+HoloSpy is maintained by the `HyperSpy community
+<https://github.com/hyperspy/holospy/contributors>`_.
+
+If HoloSpy has been significant to a project that leads to an academic
+publication, please acknowledge that fact by citing it. The DOI in the
+badge below is the `Concept DOI <https://help.zenodo.org/faq/#versioning>`_ --
+it can be used to cite the project without referring to a specific
+version. If you are citing HoloSpy because you have used it to process data,
+please use the DOI of the specific version that you have employed. You can
+find it by clicking on the DOI badge below:
+
+.. image:: https://zenodo.org/badge/doi/10.5281/zenodo.10137993.svg
+    :class: sd-bg-transparent
+    :alt: doi: 10.5281/zenodo.10137993
+    :target: https://doi.org/10.5281/zenodo.10137993
+
+
+License
+=======
+
+HoloSpy is free software: you can redistribute it and/or modify
+it under the terms of the `GNU General Public License (GPL)
+<https://www.gnu.org/licenses/#GPL>`_ as published by
+the Free Software Foundation, either version 3 of the license, or
+(at your option) any later version.
+
+HoloSpy is distributed in the hope that it will be useful,
+but **without any warranty**; without even the implied warranty of
+**merchantability** or **fitness for a particular purpose**. See the
+`GNU General Public License <https://www.gnu.org/licenses/#GPL>`_
+for more details.

pyproject.toml

@@ -56,6 +56,7 @@ doc = [
   "numpydoc",
   "pydata-sphinx-theme>=0.13",
   "sphinx",
+  "sphinx-design",
   "sphinx-favicon",
   "sphinxcontrib-towncrier",
   "towncrier",