Refactor: Changes suggested by @hakonanes

doc/conf.py

@@ -52,6 +52,8 @@
     "sphinx.ext.inheritance_diagram",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
+    "sphinx.ext.linkcode",
+    "sphinx_codeautolink",
     "sphinx_gallery.gen_gallery",
     "sphinx_copybutton",
     "nbsphinx",
@@ -96,7 +98,7 @@
 html_theme_options = {
     "github_url": "https://github.com/pyxem/pyxem",
     "header_links_before_dropdown": 7,
-    "navigation_with_keys": False,
+    "navigation_with_keys": True,
     "show_toc_level": 2,
     "use_edit_page_button": True,
 }

doc/dev_guide/contributing.rst

@@ -187,12 +187,8 @@ The easiest way to download the ``pyxem-demos`` repository is to use the ``git c
 command to checkout the repository.
 
 command::
-   cd doc/tutorial
-   git clone https://github.com/pyxem/pyxem-demos.git
-
-Then, build the documentation from the ``doc`` directory::
-
    cd doc
+   git clone https://github.com/pyxem/pyxem-demos.git tutorials/pyxem-demos || echo "You have already cloned this repo try using git pull to update the demos"
    make html
 
 The documentation's HTML pages are built in the ``doc/_build/html`` directory from files
@@ -206,10 +202,10 @@ Tips for writing Jupyter notebooks that are meant to be converted to reST text f
 
 - Use ``_ = ax[0].imshow(...)`` to disable Matplotlib output if a Matplotlib
   command is the last line in a cell.
-- Refer to our API reference with this general MD
+- Refer to our API reference with this general markdown syntax.
   ``[azimuthal_integrator2d()](reference.rst#pyxem.signals.DiffractionSignal2D.azimuthal_integrator2d)``.
   Remember to add the parentheses ``()``.
-- Reference external APIs via standard MD like
+- Reference external APIs via standard markdown like
   ``[Signal2D](http://hyperspy.org/hyperspy-doc/current/api/hyperspy._signals.signal2d.html)``.
 - The Sphinx gallery thumbnail used for a notebook is set by adding the
   ``nbsphinx-thumbnail`` tag to a code cell with an image output. The notebook

doc/dev_guide/intro.rst

@@ -10,14 +10,14 @@ We welcome contributions of all kinds, including bug reports,
 feature requests, documentation improvements, and code contributions.
 
 The best way to get started is to start using pyxem and share your workflows and data with
-us and the community. You can do this by adding notebooks pyxem-demos` which will then be hosted in
-the :ref:`tutorials<Tutorials>` section of the documentation
+us and the community. You can do this by adding notebooks to the ``pyxem-demos`` which will then be hosted in
+the :doc:`/tutorials/index` section of the documentation
 
 If you have snippits of code that you think would be useful to others, you can also add them to the
 :ref:`examples<examples-index>` section of the documentation. This is a great way to share your
 workflows and data with the community!
 
 
-Other wise the :ref:`contributing` section of the documentation contains more information on how to
+The :ref:`contributing` section of the documentation contains more information on how to
 create a pull request and contribute to the code base!
 

doc/intro.rst

@@ -2,7 +2,7 @@
 pyxem's Documentation
 =====================
 
-Pyxem is an open source project working to bring together tools for the analysis of
+Pyxem is an open-source project working to bring together tools for the analysis of
 data from pixelated electron detectors. Based on the HyperSpy project, pyxem has an
 active community of users and developers who are working to develop new tools for
 4-D, 5-D STEM and other pixelated electron detector data.

doc/tutorials/index.rst

@@ -5,7 +5,8 @@ Tutorials
 
 Below are a series of tutorials that demonstrate how to use the
 ``pyxem`` package.  The tutorials are written in Jupyter notebooks
-and show complete workflows for common tasks in electron microscopy.
+and show complete workflows for common tasks in transmission electron microscopy
+analysis.
 
 For smaller snippets of code, see the Examples section of the documentation.
 

doc/user_guide/distributed_big_data.rst

@@ -3,7 +3,7 @@
 Big Data
 ---------
 
-4-D STEM datasets are large and difficult to work with.  In ``pyxem`` we get around this by
+4-D STEM datasets are large and difficult to work with.  In ``pyxem`` we try to get around this by
 using a lazy loading approach.  This means that the data is not loaded into memory until it is
 needed.
 
@@ -19,31 +19,32 @@ Loading and Plotting a Dataset
 ------------------------------
 
 Let's start by loading a dataset.  We will use the ``load`` function to load a dataset from
-hyperspy
+HyperSpy
 
 .. code-block:: python
 
     >>> import hyperspy.api as hs
     >>> s = hs.load("big_data.zspy", lazy=True)
     >>> s
 
-The dataset here is not loaded into memory here so this should happen instantaneously. We can
+The dataset here is not loaded into memory here, so this should happen instantaneously. We can
 then plot the dataset.
 
 .. code-block:: python
 
     >>> s.plot()
 
-Which (in general) will be very slow.  This is because the data is being loaded into memory and a
-navigator image is being generated before the plot is shown. In many cases a HAAADF dataset will be
-collected as well as a 4-D STEM dataset.  In this case we can set the navigator to the HAAADF dataset instead.
+Which (in general) will be very slow.  This is because entire dataset is loaded into memory (chuck by chunk)
+to create a navigator image. In many cases a HAADF dataset will be collected as well as a 4-D STEM dataset.
+In this case we can set the navigator to the HAADF dataset instead.
 
 .. code-block:: python
-    >>> haadf = hs.load("haadf.zspy") # load the HAAADF dataset
-    >>> s.naviagtor = haadf # set the navigator to the HAAADF dataset
+    >>> haadf = hs.load("haadf.zspy") # load the HAADF dataset
+    >>> s.navigator = haadf # set the navigator to the HAADF dataset
     >>> s.plot() # happens instantaneously
 
-This is much faster now to view the dataset!
+This is much faster as the navigator doesn't need to be computed and instead only 1 chunk needs to
+be loaded into memory before plotting!
 
 
 Distributed Computing

doc/user_guide/index.rst

@@ -27,7 +27,7 @@
     cite.rst
     open_datasets_workflows.rst
     related_projects.rst
-    License <https://github.com/pyxem/pyxem/blob/develop/LICENSE>
+    License <https://github.com/pyxem/pyxem/main/develop/LICENSE>
 
 .. include::
     intro.rst

doc/user_guide/installing.rst

@@ -1,15 +1,15 @@
 .. _Installation:
-
+----------------
 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>`
-which is a pre-configured python environment that includes pyxem and all its dependencies.
+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>`.
+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
-as py4dSTEM, AbTEM, and hyperspy. It also includes the Jupyter notebook and Jupyter lab pre-configured
+as Py4dSTEM, abTEM, and HyperSpy. It also includes the Jupyter notebook and Jupyter lab pre-configured
 as well as dask-distributed for parallel computing and the ipywidgets for interactive
 visualisation.
 
@@ -21,20 +21,26 @@ into an existing environment. The easiest way to do this is using conda/mamba.
 
 .. note::
    Installing some of the visualization tools such as ipympl install much better using
-   mamba than conda. If you are having trouble installing pyxem, try using mamba instead
+   mamba than conda. If you are having trouble installing pyxem, try using mamba instead.
+
+   ipympl is a backend for matplotlib that allows for interactive plotting in the Jupyter
+   but is particularly a pain sometimes. If you have having trouble you can always change
+   your url from http://localhost:8888/lab to http://localhost:8888/notebooks and use the
+   classic notebook instead. There are less features but it is more stable in my experience.
 
 ```
-conda install -c conda-forge pyxem
+    conda install -c conda-forge pyxem
 ```
 
+
 Installing using pip
 --------------------
 
 You can also install pyxem using pip if you want. In that case you can install pyxem
 using
 
 ```
-pip install pyxem
+    pip install pyxem
 ```
 
 Installing from source
@@ -44,17 +50,17 @@ If you want to install the development version of pyxem, you can install it from
 First clone the repository using
 
 ```
-git clone https://github.com/pyxem/pyxem.git
+    git clone https://github.com/pyxem/pyxem.git
 ```
 
-Then cd into the pyxem directory and install the dependencies using
+Then navigate into the pyxem directory and install the dependencies using
 
 ```
-pip install -r requirements.txt
+    pip install -r requirements.txt
 ```
 
 Finally, install pyxem using
 
 ```
-pip install . -e
+    pip install -e .
 ```

doc/user_guide/intro.rst

@@ -11,25 +11,25 @@ There are a number of resources available to help you get started with pyxem:
 - :ref:`User Guide`: The user guide contains more detailed information on how to use pyxem. It helps
   you get started with pyxem and contains more detailed information on how to use the
   different features of pyxem.
-- :ref:`Examples<examples-index>`: A collection of small scripts and snippets of code to help preform common
+- :ref:`Examples<examples-index>`: A collection of small scripts and snippets of code to help perform common
   operations. This is a good place to start if you want to build your own analysis.
 - :ref:`Tutorials`: A collection of tutorials and workflows to help you get started with a wide
   range of analysis techniques. These are more detailed than the examples and are designed
   as complete workflows.
 - :ref:`API Reference`: The API reference contains a description of all the functions and classes
   in pyxem. This is useful if you are looking for a specific function or want to know what
-  a function does/ what arguments it takes. It also includes some more detailed information
+  a function does/what arguments it takes. It also includes some more detailed information
   on what a function does.
 - :ref:`Developer Guide<development>`: The developer guide contains information on how to contribute to pyxem!
 
 Additionally, there is a bibliography of papers that have used pyxem and a list of related
 projects.
 
-For more information and additional resources, pyxem inherits from HyperSpy, so you can
-also check out the `HyperSpy documentation <https://hyperspy.org/hyperspy-doc/current/>`_.
-All of the HyperSpy documentation is relevant to pyxem, but specifically the
-`Big Data <https://hyperspy.org/hyperspy-doc/dev/user_guide/big_data.html>`_ section has
-lots of useful information on how to work with large datasets.
+pyxem inherits lots of functionality from HyperSpy. We suggest that you
+also check out the `HyperSpy documentation <https://hyperspy.org/hyperspy-doc/current/>`_ for
+more information and additional resources. All of the HyperSpy documentation is relevant to
+pyxem. Especially the `Big Data <https://hyperspy.org/hyperspy-doc/dev/user_guide/big_data.html>`_ section,
+which has lots of useful information on how to work with large datasets.
 
 Developers will also find the
 `HyperSpy Developer Guide <https://hyperspy.org/hyperspy-doc/current/dev_guide/intro.html>`_

doc/user_guide/loading_data.rst

@@ -6,11 +6,11 @@ Loading Data
 
 Data can be loaded from many different 4-D STEM detectors using the package
 `rosettasciio<https://hyperspy.org/rosettasciio>`_. The file types currently supported are listed
-`here<https://hyperspy.org/rosettasciio/supported_formats/index.html>`_
+`here<https://hyperspy.org/rosettasciio/supported_formats/index.html>`_.
 
 We are always looking to add more detectors to the list. If you have a detector that you
 would like to see added, please raise an `issue<https://github.com/hyperspy/rosettasciio/issues>`_
-on the rosettasciio github page and we will do our best to work with you to add it.
+on the rosettasciio GitHub page and we will do our best to work with you to add it.
 
 We are also looking to add support for faster loading of data from detectors that we already
 support.  This means adding support for distributed file loading, which allows for operating