Merge pull request #957 from CSSFrancis/documentation_follow_up

Documentation Follow Up

CHANGELOG.rst

@@ -50,7 +50,7 @@ Added
 - Center-of-mass algorithm added to get_direct_beam_position (#845)
 - Added `VectorSignal1D` class to handle 1 dimensional signals
 - Added kwargs to find_beam_offset_cross_correlation allowing for parameters
-to be passed to `phase_cross_correlation` (#907)
+  to be passed to `phase_cross_correlation` (#907)
 - Added `LazyVirtualDarkField` signal
 
 Changed
@@ -108,6 +108,7 @@ Removed
 - lazy_* virtual imaging has been removed, use get_integrated_intensity (#722)
 - `big_data_utils` has been removed as this is not the modern way of attacking this problem
 - similarly, `TemplateIndexationGenerator` has been removed as the Accelerated approach is far better (#823)
+
 Fixed
 ^^^^^
 - Symmetry STEM Class updated to allow for better interpolation and lazy operation. (#809)

doc/conf.py

@@ -79,6 +79,8 @@
 linkcheck_ignore = [
     "https://doi.org/10.1002/smll.201904738",  # 403 Client Error: Forbidden for url
     "http://dx.doi.org/10.1088/0965-0393/23/8/083501",  # 403 Client Error: Forbidden for url
+    "https://doi.org/10.1111/jmi.12065",  # 403 Client Error: Forbidden for url
+    "https://doi.org/10.1111/j.0022-2720.2004.01293.x",  # 403 Client Error: Forbidden for url
 ]
 
 

doc/dev_guide/contributing.rst

@@ -22,6 +22,7 @@ inquiries regarding the project? Feel free to
 repository.
 
 .. _setting-up-a-development-installation:
+
 First Time Contributing
 =======================
 

doc/dev_guide/index.rst

@@ -1,3 +1,5 @@
+.. _development:
+
 .. toctree::
   :maxdepth: 1
   :hidden:

doc/dev_guide/intro.rst

@@ -1,5 +1,3 @@
-.. _development:
-
 ##########
 Contribute
 ##########

doc/user_guide/bibliography.rst

@@ -1,5 +1,5 @@
 Bibliography
 =============
 
-.. bibliography:: bibliography.bib
+.. bibliography:: ../bibliography.bib
     :all:

doc/user_guide/distributed_big_data.rst

@@ -1,5 +1,3 @@
-.. _Big Data:
-
 Big Data
 ---------
 
@@ -12,44 +10,47 @@ discuss how to work with large datasets in ``pyxem``.
 
 .. note::
     If you want more information on working with large datasets in ``pyxem``, please see the
-    `Big Data<https://hyperspy.org/hyperspy-doc/current/user_guide/big_data.html>_` section of
-    the `HyperSpy User Guide<https://hyperspy.org/hyperspy-doc/current/user_guide/index.html>`_.
+    `Big Data <https://hyperspy.org/hyperspy-doc/current/user_guide/big_data.html>_` section of
+    the `HyperSpy User Guide <https://hyperspy.org/hyperspy-doc/current/user_guide/index.html>_`.
 
 Loading and Plotting a Dataset
 ------------------------------
 
 Let's start by loading a dataset.  We will use the ``load`` function to load a dataset from
 HyperSpy
 
-.. code-block:: python
+.. code-block::
 
-    >>> import hyperspy.api as hs
-    >>> s = hs.load("big_data.zspy", lazy=True)
-    >>> s
+    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
 then plot the dataset.
 
-.. code-block:: python
+.. code-block::
 
-    >>> s.plot()
+    s.plot()
 
 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 HAADF dataset
-    >>> s.plot(navigator=haadf) # happens instantaneously
+
+    haadf = hs.load("haadf.zspy") # load the HAADF dataset
+    s.plot(navigator=haadf) # happens instantaneously
 
 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!
 
 You can also set the navigator so that by default it is used when plotting.
+
 .. code-block:: python
-    >>> haadf = hs.load("haadf.zspy") # load the HAADF dataset
-    >>> s.navigator = haadf
-    >>> s.plot() # (navigator=haadf) happens instantaneously
+
+    haadf = hs.load("haadf.zspy") # load the HAADF dataset
+    s.navigator = haadf
+    s.plot()
 
 
 Distributed Computing
@@ -62,20 +63,20 @@ in Python.  It is very powerful and can be used to speed up many different types
 The first step is to set up a `Dask Client <https://distributed.dask.org/en/latest/client.html>`_.
 This can be done using the distributed scheduler.
 
-.. code-block:: python
+.. code-block::
 
-    >>> from dask.distributed import Client
-    >>> client = Client()
+    from dask.distributed import Client
+    client = Client()
 
 This will start a local cluster on your machine.
 
 If you want to use a remote cluster using a scheduler such as `Slurm <https://slurm.schedmd.com/>`_
 you can do so by using the `dask-jobqueue <https://jobqueue.dask.org/en/latest/>`_ library.
 This is a library that allows you to use a scheduler to start a cluster on a remote machine.
 
-.. code-block:: python
+.. code-block::
 
-    >>> from dask_jobqueue import SLURMCluster
-    >>> cluster = SLURMCluster()
-    >>> client = Client(cluster)
+    from dask_jobqueue import SLURMCluster
+    cluster = SLURMCluster()
+    client = Client(cluster)
 

doc/user_guide/index.rst

@@ -1,3 +1,5 @@
+.. _User Guide:
+
 .. toctree::
      :maxdepth: 1
      :hidden:
@@ -23,7 +25,7 @@
     :caption: Resources
     :hidden:
 
-    reference/index.rst
+    ../reference/index.rst
     bibliography.rst
     cite.rst
     open_datasets_workflows.rst

doc/user_guide/installing.rst

@@ -1,11 +1,12 @@
 .. _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>`.
+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
@@ -27,40 +28,31 @@ into an existing environment. The easiest way to do this is using conda/mamba.
    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
-```
-
 
 Installing using pip
 --------------------
 
 You can also install pyxem using pip if you want. In that case you can install pyxem
-using
+using::
 
-```
     pip install pyxem
-```
 
 Installing from source
 ----------------------
 
 If you want to install the development version of pyxem, you can install it from source.
-First clone the repository using
+First clone the repository using::
 
-```
     git clone https://github.com/pyxem/pyxem.git
-```
 
-Then navigate 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
-```
 
-Finally, install pyxem using
+Finally, install pyxem using::
 
-```
     pip install -e .
-```
+

doc/user_guide/intro.rst

@@ -1,5 +1,3 @@
-.. _User Guide:
-
 Where do I start?
 =================
 

doc/user_guide/loading_data.rst

@@ -5,10 +5,12 @@ 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>`_.
+`rosettasciio<https://hyperspy.org/rosettasciio>_`. The file types currently supported are listed
+`here<https://hyperspy.org/rosettasciio/supported_formats/index.html>_`.
 
-We are always looking to add more support for more file formats and detectors. If you have a files or detectors that you would like to see supported, please raise an `issue<https://github.com/hyperspy/rosettasciio/issues>`_
+We are always looking to add more support for more file formats and detectors.
+If you have a files or detectors that you would like to see supported,
+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.
 
 We are also looking to add support for faster loading of data from detectors that we already
@@ -26,27 +28,27 @@ and when possible it is done automatically. For example, loading:external+rsciio
 return :class:`~.signals.ElecttronDiffraction2D` object but in situations, where a generic signal is returned,
 a domain-specific signal can be specified as follow:
 
-.. code-block:: python
+.. code-block::
 
-    >>> s = hs.load("data/4DSTEM_simulation.hspy", signal_type="electron_diffraction"
-    >>> s # ElectronDiffraction2D object (defined in pyxem!)
+    s = hs.load("data/4DSTEM_simulation.hspy", signal_type="electron_diffraction")
+    s # ElectronDiffraction2D object (defined in pyxem!)
 
 Or we can cast the signal to a specific signal type after loading it.  For example,
 
-.. code-block:: python
+.. code-block::
 
-    >>> s = hs.load("data/4DSTEM_simulation.hspy")
-    >>> s = s.set_signal_type("electron_diffraction")
-    >>> s # ElectronDiffraction2D object (defined in pyxem!)
+    s = hs.load("data/4DSTEM_simulation.hspy")
+    s = s.set_signal_type("electron_diffraction")
+    s # ElectronDiffraction2D object (defined in pyxem!)
 
 Note that when we save the signal to a ``.zspy`` file or a ``.hspy`` file, the signal type
 is saved as metadata.  This means that when we load the signal, we no longer need to specify
 the signal type.  For example,
 
-.. code-block:: python
+.. code-block::
 
-    >>> s = hs.load("data/4DSTEM_simulation.zspy")
-    >>> s.set_signal_type("electron_diffraction")
-    >>> s.save("data/4DSTEM_simulation_2.zspy")
-    >>> s = hs.load("data/4DSTEM_simulation_2.zspy")
-    >>> s # ElectronDiffraction2D object (defined in pyxem!)
+    s = hs.load("data/4DSTEM_simulation.zspy")
+    s.set_signal_type("electron_diffraction")
+    s.save("data/4DSTEM_simulation_2.zspy")
+    s = hs.load("data/4DSTEM_simulation_2.zspy")
+    s # ElectronDiffraction2D object (defined in pyxem!)

pyxem/signals/diffraction2d.py

@@ -1405,7 +1405,7 @@ def intensity_peaks(
         disk_r : int
             Radius of the disc chosen to take the mean value of
         lazy_result : bool, default True
-            If True, will return a LazyDiffraction2D object. If False,
+            If True, will return a :class:`~pyxem.signals.diffraction2d.LazyDiffraction2D` object. If False,
             will compute the result and return a Diffraction2D object.
         show_progressbar : bool, default True
 

pyxem/signals/insitu_diffraction2d.py

@@ -42,9 +42,9 @@ class InSituDiffraction2D(Diffraction2D):
 
     Parameters
     ----------
-    *args
+    *args:
         See :class:`~hyperspy._signals.signal2d.Signal2D`.
-    **kwargs
+    **kwargs:
         See :class:`~hyperspy._signals.signal2d.Signal2D`
     """
 
@@ -55,12 +55,11 @@ def roll_time_axis(self, time_axis):
         return self.rollaxis(time_axis, 2)
 
     def get_time_series(self, roi=None, time_axis=2):
-        """
-        Create a intensity time series from virtual aperture defined by roi.
+        """Create a intensity time series from virtual aperture defined by roi.
 
         Parameters
         ----------
-        roi: :obj:`hyperspy.roi.BaseInteractiveROI`
+        roi: :obj:`~hyperspy.roi.BaseInteractiveROI`
             Roi for virtual detector. If None, full roi of diffraction plane is used
         time_axis: int
             Index of time axis. Default is 2
@@ -89,26 +88,24 @@ def get_time_series(self, roi=None, time_axis=2):
     def get_drift_vectors(
         self, time_axis=2, reference="cascade", sub_pixel_factor=10, **kwargs
     ):
-        """
-        Calculate real space drift vectors from time series of images
+        """Calculate real space drift vectors from time series of images
 
-         Parameters
+        Parameters
         ----------
-        s: Signal2D
+        s: :class:`~hyperspy.api.signals.Signal2D`
             Time series of reconstructed images
         reference: 'current', 'cascade', or 'stat'
-            reference argument passed to hs.signals.Signal2D.estimate_shift2D()
+            reference argument passed to :meth:`~hyperspy.api.signals.Signal2D.estimate_shift2D`
             function. Default is 'cascade'
         sub_pixel_factor: float
-            sub_pixel_factor passed to hs.signals.Signal2D.estimate_shift2D()
+            sub_pixel_factor passed to :meth:`~hyperspy.api.signals.Signal2D.estimate_shift2D`
             function. Default is 10
         **kwargs:
-            Passed to the :meth:`get_time_series` function
+            Passed to the :meth:`~pyxem.signals.InSituDiffraction2D.get_time_series` function
 
         Returns
         -------
         shift_vectors
-
         """
         roi = kwargs.pop("roi", None)
         ref = self.get_time_series(roi=roi, time_axis=time_axis)