Update documentation

docs/source/api/select_fields_table_view.rst → docs/source/api/mda_file_table_model.rst

@@ -1,7 +1,7 @@
 ====================================
-select_fields_table_view
+mda_file_table_model
 ====================================
 
-.. automodule:: mdaviz.select_fields_table_view
+.. automodule:: mdaviz.mda_file_table_model
  :members:
  :private-members:

docs/source/api/mda_file_table_view.rst

@@ -0,0 +1,7 @@
+====================================
+mda_file_table_view
+====================================
+
+.. automodule:: mdaviz.mda_file_table_view
+ :members:
+ :private-members:

docs/source/changes.rst

@@ -0,0 +1,6 @@
+.. _changes:
+
+Changes
+=======
+
+TODO

docs/source/index.rst

@@ -1,26 +1,18 @@
-======
-mdaviz
-======
+=======================
+mdaviz: MDA Data Viewer
+=======================
 
-Python Qt5 application to visualize mda data.
 
-.. from gemviz
- .. list-table::
- :widths: 1 2
 
- * - .. figure:: _static/gemviz_gui.png
- :alt: fig.gemviz_gui
- - * Browse catalogs of Bluesky data
- * Search for data by keywords or date
- * Visualize (1-D plots now)
+Key Features
+============
 
-.. toctree::
- :maxdepth: 1
- :hidden:
+* Visualize MDA data (currently supports 1-D plots)
+* Basic mathematical information and cursor utilities
+* Fitting functionality coming soon
 
- user_guide
- install
- api
+Documentation
+=============
 
 .. icons: https://fonts.google.com/icons
 .. grid:: 3
@@ -38,9 +30,43 @@ Python Qt5 application to visualize mda data.
  :link-type: doc
 
 
-Indices and tables
-==================
+.. figure:: _static/mdaviz_gui.png
+ :alt: fig.mdaviz_gui
+ :width: 100%
+ :align: center
+ :figclass: align-center
+ :figwidth: 100%
+
+ Screenshot of the mdaviz GUI displaying a sample data set. 
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+ :caption: Contents:
+ :hidden:
+
+ user_guide
+ install
+ api
+ changes
+ license
+
+About
+=====
+
+:home: https://bcda-aps.github.io/mdaviz/
+:bug tracker: https://github.com/BCDA-APS/mdaviz/issues
+:source: https://github.com/BCDA-APS/mdaviz
+:license: :ref:`license`
+:full version: |release|
+:published: |today|
+:revisions: :ref:`History of code changes <changes>`
+:index: :ref:`genindex`
+:module: :ref:`modindex`
+:search: :ref:`search`
+
+Acknowledgements
+================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+"This product includes software produced by UChicago Argonne, LLC 
+under Contract No. DE-AC02-06CH11357 with the Department of Energy."

docs/source/install.rst

@@ -2,24 +2,54 @@
 Installation Guide
 ====================================
 
-First said, this software application is pre-release and may contain significant
-unhandled bugs. Please report any issues you encounter
-(https://github.com/BCDA-APS/mdaviz/issues/new) or feature requests, too.
-
-Suggested installation for developers is to use
-``pip`` with its *editable* mode:
-
-This project is still in development. We have plans for production release
-(https://github.com/orgs/BCDA-APS/projects/6). Until the production release, you
-should run ``mdaviz`` as would a developer by following these (Linux) instructions:
-
-1. Navigate to a directory where you have similar software projects
-2. ``git clone https://github.com/BCDA-APS/mdaviz``
- - only need to do this once, assumes you have ``git`` command
-3. ``cd mdaviz``
-4. ``conda env create --force -n mdaviz -f ./env.yml``
- - only need to do this once, assumes you have ``conda`` command
-5. ``conda activate mdaviz``
-6. ``pip install -e .``
-7. ``mdaviz &``
+The ``mdaviz`` package is available for installation by ``pip`` or from source.
+Please report any issues you encounter (https://github.com/BCDA-APS/mdaviz/issues/new) or feature requests, too.
 
+pip
+---
+
+Released versions of ``mdaviz`` are available on `PyPI
+<https://pypi.python.org/pypi/mdaviz>`_.
+
+If you have ``pip`` installed, then you can install::
+
+ $ pip install mdaviz
+
+source
+------
+
+The latest development versions of apstools can be downloaded from the
+GitHub repository listed above::
+
+ $ git clone https://github.com/BCDA-APS/mdaviz
+
+To install from the source directory using ``pip`` in editable mode::
+
+ $ cd mdaviz
+ $ python -m pip install -e .
+
+Required Libraries
+------------------
+
+The repository's ``env.yml`` file lists the additional packages
+required by ``mdaviz``. Most packages are available as conda packages
+from https://anaconda.org. The others are available on
+https://PyPI.python.org.
+
+To Run This Program
+===================
+
+For ``pip`` installation, activate the conda environment and start the application::
+
+ $ conda activate mdaviz
+ $ mdaviz
+
+For source installation, navigate to the mdaviz directory then use the same commands::
+
+ $ cd mdaviz
+ $ conda activate mdaviz
+ $ mdaviz
+
+You can also create an alias for convenience; e.g., in bash::
+
+ $ alias start_mdaviz="conda activate mdaviz; mdaviz"

docs/source/license.rst

@@ -0,0 +1,7 @@
+.. _license:
+
+License
+=======
+
+.. literalinclude:: ../../mdaviz/LICENSE
+ :language: text

mdaviz/data_table_model.py

@@ -1,25 +1,32 @@
+"""
+ .. autosummary::
+
+ ~DataTableModel
+
+"""
+
 from PyQt5 import QtCore
 from PyQt5.QtCore import QAbstractTableModel, QVariant, Qt
 
 
 class DataTableModel(QAbstractTableModel):
- """
- This model is designed to handle data represented as a dictionary where keys correspond to column labels and values are lists of data points for each column.
+ """This model is designed to handle data represented as a dictionary where keys correspond to column labels and values are lists of data points for each column.
+
 
- Parameters:
- - scanDict (dict): A dictionary where keys are pos/det indexes and values are dictionaries:
- {index: {'object': scanObject, 'data': [...], 'unit': '...', 'name': '...','type':...}}.
- - parent (QObject, optional): The parent object for this table model, default is None.
+ Args:
+  - scanDict (dict): A dictionary where keys are pos/det indexes and values are dictionaries:
+  {index: {'object': scanObject, 'data': [...], 'unit': '...', 'name': '...','type':...}}.
+  - parent (QObject, optional): The parent object for this table model, default is None.
 
  Methods:
- - rowCount: Returns the number of rows in the table model.
- - columnCount: Returns the number of columns in the table model.
- - data: Returns the data to be displayed for a given index and role.
- - headerData: Provides the header labels for the table model.
- - columnLabels: Returns a list of column labels.
- - setColumnLabels: Sets the column labels based on keys from the input dictionary.
- - allData: Returns the current data stored in the model.
- - setAllData: Sets the model's data using the input dictionary.
+  - rowCount: Returns the number of rows in the table model.
+  - columnCount: Returns the number of columns in the table model.
+  - data: Returns the data to be displayed for a given index and role.
+  - headerData: Provides the header labels for the table model.
+  - columnLabels: Returns a list of column labels.
+  - setColumnLabels: Sets the column labels based on keys from the input dictionary.
+  - allData: Returns the current data stored in the model.
+  - setAllData: Sets the model's data using the input dictionary.
 
  The model dynamically adjusts to changes in the input data, updating both the data displayed and the column headers as necessary.
  """

mdaviz/mda_file_table_model.py

@@ -23,9 +23,9 @@
 
 .. autosummary::
 
- ~SelectFieldsTableModel
+ ~MDAFileTableModel
  ~ColumnDataType
- ~FieldSelectionRuleType
+ ~FieldRuleType
  ~TableColumn
  ~TableField
 """

mdaviz/mda_file_table_view.py

@@ -128,16 +128,16 @@ def data2Plot(self, selections):
  Extracts selected datasets for plotting from scanDict based on user selections.
 
  Parameters:
- - selections: A dictionary with keys "X" and "Y", where "X" is the index for the x-axis data
- and "Y" is a list of indices for the y-axis data.
+  - selections: A dictionary with keys "X" and "Y", where "X" is the index for the x-axis data
+  and "Y" is a list of indices for the y-axis data.
 
  Returns:
- - A tuple of (datasets, plot_options), where datasets is a list of tuples containing the
- data and options (label) for each dataset, and plot_options contains overall plotting configurations.
+  - A tuple of (datasets, plot_options), where datasets is a list of tuples containing the
+  data and options (label) for each dataset, and plot_options contains overall plotting configurations.
 
- ..note::
- scanDict = {index: {'object': scanObject, 'data': [...], 'unit': '...', 'name': '...',
-  'type':...}}.
+ .. note::
+
+ scanDict = {index: {'object': scanObject, 'data': [...], 'unit': '...', 'name': '...','type':...}}.
  """
 
  datasets, plot_options = [], {}

mdaviz/utils.py

@@ -55,14 +55,13 @@ def num2fstr(x):
 
 def byte2str(byte_literal):
  """
- Converts a byte literal to a UTF-8 encoded string.
- If the input is not a byte literal, it is returned as is without any conversion.
+ Converts a byte literal to a UTF-8 encoded string. If the input is not a byte literal, it is returned as is without any conversion.
 
  Parameters:
- - byte_literal (bytes | Any): The byte literal to be decoded or any input to be returned as is if not bytes.
+  - byte_literal (bytes | Any): The byte literal to be decoded or any input to be returned as is if not bytes.
 
  Returns:
- - str | Any: The decoded string if the input is a byte literal, otherwise the original input.
+  - str | Any: The decoded string if the input is a byte literal, otherwise the original input.
  """
  return (
  byte_literal.decode("utf-8")
@@ -81,19 +80,19 @@ def get_det(mda_file_data):
  The first detector is labeled D01 and subsequent detectors follow in numerical order.
 
  Parameters:
- - mda_file_data: An instance of an mda.scanDim object, which contains the MDA file data to be processed.
+  - mda_file_data: An instance of an mda.scanDim object, which contains the MDA file data to be processed.
 
  Returns:
- - A tuple containing:
- - A dictionary (d) where keys are indexes, mapping to either scanPositioner or scanDetector objects.
- The dictionary is structured as {0: p0, 1: P1, ..., np: D01, np+1: D02, ..., np+nd: DX}.
- - The index (first_pos) of the first positioner in the returned dictionary. This is 1 if a positioner
- other than the default index positioner exists, otherwise 0.
- - The index (first_det) of the first detector in the returned dictionary, which directly follows the last positioner.
-
- Note:
- - p0 is created by default and corresponds to the point index, described as an 'Index' scanPositioner object with predefined properties.
- - np is the total number of positioners, nd the number of detectors, and npts the number of data points actually acquired.
+  - A tuple containing:
+  - A dictionary (d) where keys are indexes, mapping to either scanPositioner or scanDetector objects.
+  The dictionary is structured as {0: p0, 1: P1, ..., np: D01, np+1: D02, ..., np+nd: DX}.
+  - The index (first_pos) of the first positioner in the returned dictionary. This is 1 if a positioner
+  other than the default index positioner exists, otherwise 0.
+  - The index (first_det) of the first detector in the returned dictionary, which directly follows the last positioner.
+
+ ..note::
+  - p0 is created by default and corresponds to the point index, described as an 'Index' scanPositioner object with predefined properties.
+  - np is the total number of positioners, nd the number of detectors, and npts the number of data points actually acquired.
  """
 
  d = {}
@@ -141,19 +140,18 @@ def get_scan(mda_file_data):
  follow in numerical order: p0, p1,... px, d01, d02,... dX.
 
  Parameters:
- - mda_file_data: An instance of an mda.scanDim object to be processed.
+  - mda_file_data: An instance of an mda.scanDim object to be processed.
 
  Returns:
- - A tuple containing:
- - A dictionary keyed by index, each mapping to a sub-dictionary containing
- the scan object ('object') along with its 'data', 'unit', 'name' and 'type'.
- Structure:
- {index: {'object': scanObject, 'data': [...], 'unit': '...', 'name': '...',
- 'type':...}}.
- - The index (first_pos) of the first positioner in the returned dictionary. This
- is 1 if a positioner other than the default index positioner exists, otherwise 0.
- - The index (first_det) of the first detector in the returned dictionary, which
- directly follows the last positioner.
+ - A tuple containing:
+ - A dictionary keyed by index, each mapping to a sub-dictionary containing
+ the scan object ('object') along with its 'data', 'unit', 'name' and 'type'.
+ Structure:
+ {index: {'object': scanObject, 'data': [...], 'unit': '...', 'name': '...','type':...}}.
+ - The index (first_pos) of the first positioner in the returned dictionary. This
+ is 1 if a positioner other than the default index positioner exists, otherwise 0.
+ - The index (first_det) of the first detector in the returned dictionary, which
+ directly follows the last positioner.
  """
 
  d = {}