Tweak documentation

doc/conf.py

@@ -39,6 +39,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinxcontrib.towncrier",
+    "sphinx_copybutton",
 ]
 
 intersphinx_mapping = {
@@ -120,6 +121,13 @@
 towncrier_draft_include_empty = False
 towncrier_draft_working_directory = ".."
 
+# -- Options for CopyButton extension -----------------------------------
+
+# CopyButton configuration
+copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True
+copybutton_line_continuation_character = "\\"
+
 
 linkcheck_ignore = [
     "https://www.biorxiv.org",  # 403 Client Error: Forbidden for url

doc/user_guide/supported_formats/mrc.rst

@@ -14,10 +14,10 @@ and has partial support for FEI's custom header.
     specify the shape of the navigation space.
 
 .. Note::
-    For ``.mrc`` files, the ``file_reader`` takes the ``mmap_mode`` keyword argument
-    to load the file using a different mode (default is copy-on-write) . However,
-    note that lazy loading does not support in-place writing (i.e lazy loading and
-    the ``r+`` mode are incompatible).
+    For ``.mrc`` files, the :func:`~rsciio.mrc.file_reader` takes the ``mmap_mode``
+    keyword argument to load the file using a different mode (default is copy-on-write).
+    However, note that lazy loading does not support in-place writing (i.e lazy loading
+    and the ``r+`` mode are incompatible).
 
 See also the `format documentation <https://www.ccpem.ac.uk/mrc_format/mrc_format.php>`_
 by the Collaborative Computational Project for Electron cryo-Microscopy (CCP-EM).
@@ -30,26 +30,26 @@ not be passed (Default is ``None``):
 
 .. code-block:: python
 
-    import numpy as np
-    from rsciio import mrcz
+    >>> import numpy as np
+    >>> from rsciio import mrcz
 
-    data = np.random.randint(100, size=(10, 100, 100)).astype('int16')
-    s = hs.signals.Signal2D(data)
-    s_dict = s.as_dictionary()
+    >>> data = np.random.randint(100, size=(10, 100, 100)).astype('int16')
+    >>> s = hs.signals.Signal2D(data)
+    >>> s_dict = s.as_dictionary()
 
-    mrcz.file_writer('test.mrc', s_dict)
+    >>> mrcz.file_writer('test.mrc', s_dict)
 
-Alternatively, use :py:meth:`hyperspy.api.signals.BaseSignal.save`, which will pick the
+Alternatively, use :meth:`hyperspy.api.signals.BaseSignal.save`, which will pick the
 ``mrcz`` plugin automatically:
 
 .. code-block:: python
 
-    import hyperspy.api as hs
-    import numpy as np
+    >>> import hyperspy.api as hs
+    >>> import numpy as np
 
-    data = np.random.randint(100, size=(10, 100, 100)).astype('int16')
-    s = hs.signals.Signal2D(data)
-    s.save("data.mrc")
+    >>> data = np.random.randint(100, size=(10, 100, 100)).astype('int16')
+    >>> s = hs.signals.Signal2D(data)
+    >>> s.save("data.mrc")
 
 MRC Format (Direct Electron)
 ----------------------------
@@ -62,7 +62,7 @@ named ``uniqueid_suffix_info.txt``.
 
 This will automatically set the navigation shape based on the ``Scan - Size X`` and                                                   = 256
 ``Scan - Size Y`` parameters in the metadata file. The navigation shape can be overridden
-by passing the ``navigation_shape`` argument to the ``file_reader`` function.
+by passing the ``navigation_shape`` argument to the :func:`~rsciio.mrc.file_reader` function.
 
 Additionally virtual_images/ external detectors can be loaded by passing a list of file names to the
 ``external_images`` or the ``virtual_images`` parameter.  This will also automatically be inferred
@@ -72,16 +72,36 @@ for fast plotting.
 
 .. code-block:: python
 
-    import hyperspy.api as hs
+    >>> import hyperspy.api as hs
+
+    # Automatically load metadata_file="20220101_0001_info.txt" and
+    # any external/virtual images with the same naming convention
+    
+    >>> hs.load("20220101_0001_movie.mrc")
+    <Signal2D, title: 20220101_0001_movie, dimensions: (32, 32|256, 256)>
+    
+    # Load metadata from data_info.txt
+    
+    >>> hs.load("data.mrc", metadata_file="data_info.txt") 
+
+    # Load external image 1
+
+    >>> s = hs.load(
+    ...     "20220101_0001_movie.mrc",
+    ...     external_images=["20220101_0001_ext1_Ext #1.mrc"]
+    ... )
+    >>> s.metadata["General"]["external_detectors"][0]
+    <Signal2D, title:, dimensions: (|32,32)>
+
+    # Will load virtual image 1
+
+    >>> s = hs.load(
+    ...     "20220101_0001_movie.mrc",
+    ...     virtual_images=["20220101_0001_1_Virtual #1.mrc"]
+    ... )
+    >>> s.metadata["General"]["virtual_images"][0]
+    <Signal2D, title:, dimensions: (|32,32)>
 
-    # Will automatically load metadata_file="20220101_0001_info.txt" and any external/virtual images with the same naming convention
-    s = hs.load("20220101_0001_movie.mrc")
-    s # <Signal2D, title: 20220101_0001_movie, dimensions: (32, 32|256, 256)>
-    hs.load("data.mrc", metadata_file="data_info.txt") # Will load metadata from data_info.txt
-    s = hs.load("20220101_0001_movie.mrc", external_images=["20220101_0001_ext1_Ext #1.mrc"]) # Will load external image 1
-    s.metadata["General"]["external_detectors"][0] # <Signal2D, title:, dimensions: (|32,32)>
-    s = hs.load("20220101_0001_movie.mrc", virtual_images=["20220101_0001_1_Virtual #1.mrc"]) # Will load virtual image 1
-    s.metadata["General"]["virtual_images"][0] # <Signal2D, title:, dimensions: (|32,32)>
 
 API functions
 ^^^^^^^^^^^^^

pyproject.toml

@@ -116,6 +116,7 @@ doc = [
   "sphinx",
   "sphinx-favicon",
   "sphinxcontrib-towncrier",
+  "sphinx-copybutton",
   # unpin when sphinxcontrib-towncrier supports towncrier >=24
   "towncrier<24",
 ]

rsciio/mrc/_api.py

@@ -308,7 +308,7 @@ def file_reader(
     external_images=None,
 ):
     """
-    File reader for the MRC format for tomographic data.
+    File reader for the MRC format for tomographic and 4D-STEM data.
 
     Parameters
     ----------