Merge pull request pyxem#1109 from CSSFrancis/doc_improvements

Clean up documentation

doc/_static/switcher.json

@@ -6,9 +6,13 @@
     },
     {
         "name": "stable",
-        "version": "0.18.0",
+        "version": "0.19.0",
         "url": "https://pyxem.readthedocs.io/en/stable/"
     },
+    {
+        "version": "0.18.0",
+        "url": "https://pyxem.readthedocs.io/en/v0.18.0/"
+    },
     {
         "version": "0.17.0",
         "url": "https://pyxem.readthedocs.io/en/v0.17.0/"

doc/conf.py

@@ -107,9 +107,6 @@
     "navigation_with_keys": True,
     "show_toc_level": 2,
     "use_edit_page_button": True,
-    "announcement": "Check out the "
-    "<a href='https://www.diamond.ac.uk/Home/Events/2024/HyperSpy-Workshop-2024.html'>Hyperspy Workshop</a> "
-    "May 13-17, 2024 Online",
     "switcher": {
         "json_url": "https://pyxem.readthedocs.io/en/latest/_static/switcher.json",
         "version_match": version_match,
@@ -149,40 +146,7 @@
     release_version = "master"
 else:
     release_version = "v" + version
-# This is processed by Jinja2 and inserted before each notebook
-nbsphinx_prolog = (
-    r"""
-{% set docname = 'doc/' + env.doc2path(env.docname, base=None) %}
-.. raw:: html
-    <style>a:hover { text-decoration: underline; }</style>
-    <div class="admonition note">
-      This page was generated from
-      <a class="reference external" href="https://github.com/pyxem/pyxem-demos/blob/"""
-    + f"{release_version}"
-    + r"""/{{ docname|e }}">{{ docname|e }}</a>.
-      Interactive online version:
-      <span style="white-space: nowrap;"><a href="https://mybinder.org/v2/gh/pyxem/pyxem-demos/"""
-    + f"{release_version}"
-    + r"""?filepath={{ docname|e }}"><img alt="Binder badge" src="https://mybinder.org/badge_logo.svg" style="vertical-align:text-bottom"></a>.</span>
-      <script>
-        if (document.location.host) {
-          $(document.currentScript).replaceWith(
-            '<a class="reference external" ' +
-            'href="https://nbviewer.jupyter.org/url' +
-            (window.location.protocol == 'https:' ? 's/' : '/') +
-            window.location.host +
-            window.location.pathname.slice(0, -4) +
-            'ipynb">View in <em>nbviewer</em></a>.'
-          );
-        }
-      </script>
-    </div>
-.. raw:: latex
-    \nbsphinxstartnotebook{\scriptsize\noindent\strut
-    \textcolor{gray}{The following section was generated from
-    \sphinxcode{\sphinxupquote{\strut {{ docname | escape_latex }}}} \dotfill}}
-"""
-)
+
 # https://nbsphinx.readthedocs.io/en/0.8.0/never-execute.html
 nbsphinx_execute = "never"  # auto, always, never
 nbsphinx_kernel_name = "python3"

doc/user_guide/index.rst

@@ -10,6 +10,7 @@
     :hidden:
 
     installing.rst
+    using_a_jupyter_notebook.rst
     loading_data.rst
     distributed_big_data.rst
     gpu_computations.rst

doc/user_guide/installing.rst

@@ -6,7 +6,7 @@ Installing pyxem
 
 There are a couple of different ways to install pyxem. The easiest way is to use the
 hyperspy-bundle. If you don't have much experience with managing Python environments, we
-highly recommend using the `hyperspy-bundle<https://hyperspy.org/hyperspy-bundle/download.html>_`.
+highly recommend using the `hyperspy-bundle <https://hyperspy.org/hyperspy-bundle/download.html>`_.
 The bundle is a pre-configured Python environment that includes pyxem and all its dependencies.
 
 It includes many other packages that are useful for electron microscopy data analysis, such

doc/user_guide/open_datasets_workflows.rst

@@ -4,7 +4,8 @@ Open datasets and workflows
 
 Here are some open datasets which are helpful for running some of the functions using real data:
 
-#. `Data <https://drive.google.com/open?id=11CV7_wkFIsOtDICOcil8Bo25fo0NlR9I>`_ for the demo notebooks.
+#. The :ref:`pyxem.data` module included pyxem will either download data from
+   the `zenodo <https://zenodo.org/records/11284654>`_ repo or create dummy datasets on the fly.
 
 #. 4D-STEM atomic resolution dataset of a perovskite oxide thin film: https://zenodo.org/record/4727847/files/011_big_film_512x512_updated.hspy?download=1.
 

doc/user_guide/using_a_jupyter_notebook.rst

@@ -0,0 +1,19 @@
+.. _Jupyter:
+
+-----------------
+Using Jupyter Lab
+-----------------
+
+Jupyter Lab is a powerful tool for interactive data analysis. It is a web-based
+interactive development environment that allows you to combine code, text, and
+visualizations in a single document. It is particularly useful for exploratory
+data analysis and for sharing your analysis with others.
+
+While Jupyter Lab is not required to use pyxem, it is highly recommended. The
+`Basic Usage <https://hyperspy.org/hyperspy-doc/current/user_guide/basic_usage.html>`_ section of
+the HyperSpy documentation contains a lot of useful information on how to use Jupyter Lab from
+a command line interface or using the context menu included with the Hyperspy bundle on windows
+computers.
+
+We also highly recommend using Jupyter Lab to publish full analysis workflows. This is a great way
+to share your analysis with others and to make your analysis reproducible!