Merge pull request #1028 from ericpre/fix_doc

Documentation fixes and improvement

.gitignore

@@ -70,6 +70,9 @@ instance/
 
 # Sphinx documentation
 doc/_build/
+doc/reference/generated*
+doc/examples/*
+doc/sg_execution_times.rst
 
 # PyBuilder
 target/

CHANGELOG.rst

@@ -15,6 +15,7 @@ Fixed
 - Fixed pytest failure. Changed `setup` --> `setup_method` (#997)
 - `pyxem.signals.Diffraction2D.center_of_mass` now uses the `map` function. (#1005)
 - Replace ``matplotlib.cm.get_cmap`` (removed in matplotlib 3.9) with ``matplotlib.colormaps``. (#1023)
+- Documentation fixes and improvement. (#1028)
 
 Added
 -----

doc/conf.py

@@ -12,6 +12,7 @@
 
 from pyxem import release_info
 import pyxem
+import hyperspy.api as hs
 
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -274,3 +275,7 @@ def linkcode_resolve(domain, info):
 }
 
 autosummary_generate = True
+
+
+# Enable ipywidgets GUIs to avoid error when building the documentation
+hs.preferences.GUIs.enable_ipywidgets_gui = True

doc/dev_guide/contributing.rst

@@ -213,11 +213,13 @@ 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 markdown syntax.
-  ``[azimuthal_integrator2d()](reference.rst#pyxem.signals.DiffractionSignal2D.azimuthal_integrator2d)``.
-  Remember to add the parentheses ``()``.
-- Reference external APIs via standard markdown like
-  ``[Signal2D](http://hyperspy.org/hyperspy-doc/current/api/hyperspy._signals.signal2d.html)``.
+- Refer to our API reference with this general markdown syntax:
+  :code:`:meth:`~.signals.Diffraction2D.get_azimuthal_integral1d`` which will be
+  displayed as :meth:`~.signals.Diffraction2D.get_azimuthal_integral1d` or 
+  :code:`:meth:`pyxem.signals.Diffraction2D.get_azimuthal_integral1d`` to have the full
+  path: :meth:`pyxem.signals.Diffraction2D.get_azimuthal_integral1d` 
+- Reference external APIs via standard markdown like :code:`:class:`hyperspy.api.signals.Signal2D``,
+  which will be displayed as :class:`hyperspy.api.signals.Signal2D`.
 - 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
   must be added to the gallery in the README.rst to be included in the
@@ -239,7 +241,7 @@ create a new release. Each time a new tag is pushed to the repository, the CI se
 will:
 
 1. Build the documentation.  Each tagged release will be added as a
-   `stable <https://docs.readthedocs.io/en/stable/versions.html#versioned-documentation>`_ build
+   `stable <https://docs.readthedocs.io/en/stable/versions.html>`_ build
    to `Read the Docs <https://pyxem.readthedocs.io/en/latest/>`_.
 2. Publish a new version of pyxem to `PyPI <https://pypi.org/project/pyxem/>`_.
 3. Create a new `GitHub release <https://github.com/pyxem/pyxem/releases>`_.

doc/user_guide/gpu_computations.rst

@@ -9,31 +9,46 @@ GPU support in pyxem/hyperspy is a point of active development.  Currently, the
 remains in the `beta` stage. This means that the API is not yet stable and may change as development continues
 to occur.  We are actively seeking feedback from users to help guide the development of the GPU support!
 
+The GPU support is currently limited to NVIDIA GPUs and requires the `cupy <https://cupy.dev>`_ package to be installed.
+If you are interested in increasing GPU support to other vendors, please let us know!
+
+Just a note that cuda can be a bit difficult to install depending on your hardware etc.  If you are having
+trouble, please let us know by raising an issue and we will try to help you out.
+
+
+Supported Operations
+^^^^^^^^^^^^^^^^^^^^
 
 Operations that are supported on the GPU:
-------------------------------------------
- - Basic Operations
- - 2D Azimuthal Integration
- - Template Matching
 
+- Generic Operations
+- 2D Azimuthal Integration
+- Template Matching
+
+
+Transfer Data To and From the GPU
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-You can transfer data to the GPU using the `to_gpu` method.  This method will transfer the data to the GPU
-or use dask to perform the operation in parallel.  You can transfer the data back to the CPU using the `from_gpu`.
+You can transfer data to the GPU using the :meth:`~.signals.CommonDiffraction.to_device` method.  This method
+will transfer the data to the GPU or use dask to perform the operation in parallel.  You can transfer the data
+back to the CPU using the :meth:`~.signals.CommonDiffraction.to_host` method.
 
 Note that this will be limited by the number of GPU's you have available.
 
 .. code-block::
 
     import pyxem as pxm
-    s = pxm.data.pdcusi(lazy=True)
-    s.to_gpu() # Creates a plan to transfer the data to GPU
+    s = pxm.data.pdnip_glass(lazy=True)
+    s.to_device() # Creates a plan to transfer the data to GPU
     az = s.get_azimuthal_integral2d(inplace=False) # automatically uses GPU method
-    az.from_gpu() # Creates a plan to transfer the data back to the CPU
+    az.to_host() # Creates a plan to transfer the data back to the CPU
 
+Working with Multiple GPUs
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-
-Maybe more useful is the `dask-cuda` package which allows you to use multiple GPU's or will handle the
-scheduling of the GPU operations for you without the context managing shown above.
+Maybe more useful is the `dask-cuda <https://docs.rapids.ai/api/dask-cuda/stable>`_ (linux only) package
+which allows you to use multiple GPU's or will handle the scheduling of the GPU operations for you without the
+context managing shown above.
 
 .. code-block::
 
@@ -44,15 +59,8 @@ scheduling of the GPU operations for you without the context managing shown abov
     client = Client(cluster)
 
     import pyxem as pxm
-    s = pxm.data.pdcusi(lazy=True)
-    s.to_gpu() # Creates a plan to transfer the data to GPU
+    s = pxm.data.pdnip_glass(lazy=True)
+    s.to_device() # Creates a plan to transfer the data to GPU
     az = s.get_azimuthal_integral2d(inplace=False) # automatically uses GPU method
-    az.from_gpu() # Creates a plan to transfer the data back to the CPU
+    az.to_host() # Creates a plan to transfer the data back to the CPU
     az.compute() # This will 1 transfer the data to the GPU in blocks operate and then transfer the data back to CPU
-
-
-The GPU support is currently limited to NVIDIA GPUs and requires the `cupy` package to be installed. If
-you are interested in increasing GPU support to other vendors, please let us know!
-
-Just a note that cuda can be a bit difficult to install depending on your hardware etc.  If you are having
-trouble, please let us know by raising an issue and we will try to help you out.