From 5df39ecd61a5499d11238190170e71e10cc7d26d Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Mon, 28 Oct 2024 20:22:02 +0000 Subject: [PATCH] Tweak documentation --- doc/conf.py | 8 +++ doc/user_guide/supported_formats/mrc.rst | 72 +++++++++++++++--------- pyproject.toml | 1 + rsciio/mrc/_api.py | 2 +- 4 files changed, 56 insertions(+), 27 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 41706bb8..f56e99b6 100644 --- a/doc/conf.py +++ b/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 diff --git a/doc/user_guide/supported_formats/mrc.rst b/doc/user_guide/supported_formats/mrc.rst index a34640b6..9f9038f6 100644 --- a/doc/user_guide/supported_formats/mrc.rst +++ b/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 `_ 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") + + + # 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] + + + # 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] + - # 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 # - 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] # - 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] # API functions ^^^^^^^^^^^^^ diff --git a/pyproject.toml b/pyproject.toml index 86bff894..90407421 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -116,6 +116,7 @@ doc = [ "sphinx", "sphinx-favicon", "sphinxcontrib-towncrier", + "sphinx-copybutton", # unpin when sphinxcontrib-towncrier supports towncrier >=24 "towncrier<24", ] diff --git a/rsciio/mrc/_api.py b/rsciio/mrc/_api.py index 5c2fd9eb..5370d4d7 100644 --- a/rsciio/mrc/_api.py +++ b/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 ----------