docs: fix typos and add compat notes to getting-started

kmnhan · Apr 16, 2024 · 3bb2ac5 · 3bb2ac5
1 parent 0844f6a
commit 3bb2ac5
Show file tree

Hide file tree

Showing 2 changed files with 37 additions and 22 deletions.
diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst
@@ -67,12 +67,23 @@ will be sufficient for most use cases.
 ERLabPy also requires a Qt library such as PyQt5, PyQt6, PySide2, or PySide6. To
 ensure compatibility and keep the namespace clean, ERLabPy imports Qt bindings
 from `qtpy <https://github.com/spyder-ide/qtpy>`_, which will automatically
-select the appropriate library based on what is installed. Be aware that there
-are some known compatibility issues with PyQt5 and PySide2, so it is recommended
-to use the newer PyQt6 or PySide6 if possible.
+select the appropriate library based on what is installed.
 
 See the :doc:`user-guide/index` to start using ERLabPy!
 
+Notes on compatibility
+----------------------
+
+- ERLabPy is tested on Python 3.11 and 3.12. It is not guaranteed to work on older
+  versions of Python.
+- There are some `known compatibility issues
+  <https://github.com/kmnhan/erlabpy/issues/17>`_ with PyQt5 and PySide2, so it is
+  recommended to use the newer PyQt6 or PySide6 if possible.
+- If you meet any unexpected behaviour while using IPython's `autoreload extension
+  <https://ipython.readthedocs.io/en/stable/config/extensions/autoreload.html>`_, try
+  excluding the following modules: ::
+
+    %aimport -erlab.io.dataloader -erlab.accessors
 
 Optional dependencies
 ---------------------

diff --git a/docs/source/user-guide/io.ipynb b/docs/source/user-guide/io.ipynb
@@ -229,13 +229,16 @@
                 "  be a valid path to a file.\n",
                 "\n",
                 "Suppose we have data from the ALS beamline 4.0.3 stored as ``/path/to/data/f_001.pxt``,\n",
-                "``/path/to/data/f_002.pxt``, etc. To load ``f_001.pxt``, all of the following will work:\n",
+                "``/path/to/data/f_002.pxt``, etc. To load ``f_001.pxt``, all three of the following are\n",
+                "valid:\n",
                 "\n",
                 ".. code-block:: python\n",
                 "\n",
-                "   erlab.io.loaders[\"merlin\"].load(\"/path/to/data/f_001.pxt\")\n",
-                "   erlab.io.loaders[\"merlin\"].load(\"f_001.pxt\", data_dir=\"/path/to/data\")\n",
-                "   erlab.io.loaders[\"merlin\"].load(1, data_dir=\"/path/to/data\")\n",
+                "   loader = erlab.io.loaders[\"merlin\"]\n",
+                "\n",
+                "   loader.load(\"/path/to/data/f_001.pxt\")\n",
+                "   loader.load(\"f_001.pxt\", data_dir=\"/path/to/data\")\n",
+                "   loader.load(1, data_dir=\"/path/to/data\")\n",
                 "\n",
                 "Setting the default loader and data directory\n",
                 "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n",
@@ -263,8 +266,8 @@
                 "   with erlab.io.loader_context(\"merlin\", data_dir=\"/path/to/data\"):\n",
                 "       data_1 = erlab.io.load(1)\n",
                 "\n",
-                "Data with multiple files\n",
-                "~~~~~~~~~~~~~~~~~~~~~~~~\n",
+                "Data across multiple files\n",
+                "~~~~~~~~~~~~~~~~~~~~~~~~~~\n",
                 "\n",
                 "For setups like the ALS beamline 4.0.3, some scans are stored over multiple files like\n",
                 "``f_003_S001.pxt``, ``f_003_S002.pxt``, and so on. In this case, the loader will\n",
@@ -288,10 +291,10 @@
                 "Handling multiple data directories\n",
                 "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n",
                 "   \n",
-                "If you call to :func:`erlab.io.set_loader` or :func:`erlab.io.set_data_dir` multiple\n",
-                "times, the last call will override the previous ones. While this is useful for changing\n",
-                "the loader or data directory, it makes data loading dependent on execution order. This\n",
-                "may lead to unexpected behavior.\n",
+                "If you call :func:`erlab.io.set_loader` or :func:`erlab.io.set_data_dir` multiple times,\n",
+                "the last call will override the previous ones. While this is useful for changing the\n",
+                "loader or data directory, it makes data loading *dependent on execution order*. This may\n",
+                "lead to unexpected behavior.\n",
                 "\n",
                 "If you plan to use multiple loaders or data directories in the same session, it is\n",
                 "recommended to use the context manager. If you have to load data from multiple\n",
@@ -304,29 +307,30 @@
                 "       with erlab.io.loader_context(\"merlin\", data_dir=\"/path/to/data1\"):\n",
                 "           return erlab.io.load(identifier)\n",
                 "\n",
-                "   def load2(identifier):\n",
-                "       with erlab.io.loader_context(\"merlin\", data_dir=\"/path/to/data2\"):\n",
-                "           return erlab.io.load(identifier)\n",
-                "\n",
                 "Summarizing data\n",
                 "~~~~~~~~~~~~~~~~\n",
                 "\n",
                 "Some loaders have :meth:`generate_summary\n",
                 "<erlab.io.dataloader.LoaderBase.generate_summary>` implemented, which generates a\n",
                 ":class:`pandas.DataFrame` containing an overview of the data in a given directory. The\n",
-                "generated summary can be viewed as a table with :meth:`summarize\n",
-                "<erlab.io.dataloader.LoaderBase.summarize>`. If ``ipywidgets`` is installed, an\n",
+                "generated summary can be viewed as a table with the :meth:`summarize\n",
+                "<erlab.io.dataloader.LoaderBase.summarize>` method. If ``ipywidgets`` is installed, an\n",
                 "interactive widget is also displayed. This is useful for quickly skimming through the\n",
-                "data. For example, to display a summary of the data available in the directory\n",
-                "``/path/to/data`` using the ALS Beamline 4.0.3 loader:\n",
+                "data.\n",
+                "\n",
+                "Just like :meth:`load <erlab.io.dataloader.LoaderBase.load>`, :meth:`summarize\n",
+                "<erlab.io.dataloader.LoaderBase.summarize>` can also be accessed with the shortcut\n",
+                "function :func:`erlab.io.summarize`. For example, to display a summary of the data\n",
+                "available in the directory ``/path/to/data`` using the ``'merlin'`` loader:\n",
                 "\n",
                 ".. code-block:: python\n",
                 "\n",
                 "   erlab.io.set_loader(\"merlin\")\n",
                 "   erlab.io.set_data_dir(\"/path/to/data\")\n",
                 "   erlab.io.summarize()\n",
                 "\n",
-                "To see what the summary looks like, see the :ref:`example below <summary example>`.\n",
+                "To see what the generated summary looks like, see the :ref:`example below <summary\n",
+                "example>`.\n",
                 "\n",
                 "Implementing a data loader plugin \n",
                 "---------------------------------\n",