Docs and docstrings

.readthedocs.yaml

@@ -12,7 +12,7 @@ python:
 
 sphinx:
   builder: html
-  configuration: docs/source/conf.py
+  configuration: docs/conf.py
   fail_on_warning: true
 
 conda:

docs/Makefile

@@ -0,0 +1,21 @@
+# Purpose: Convenience scripts to simplify some common Sphinx operations, such as rendering the content.
+
+# Minimal makefile for Sphinx documentation
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -39,6 +39,14 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
 ]
+
+autodoc_mock_imports = [
+    "qtpy",
+    "qtpy.uic",
+    "qtpy.QtWidgets",
+    "mantidqt",
+]
+
 templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
@@ -47,7 +55,7 @@
 source_suffix = [".rst", ".md"]
 
 # The master toctree document.
-master_doc = "index"
+master_doc = "source/index"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -69,7 +77,7 @@
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
 
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True

docs/make.bat

@@ -0,0 +1,37 @@
+REM Purpose: Convenience scripts to simplify some common Sphinx operations, such as rendering the content.
+
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/index.rst

@@ -0,0 +1,32 @@
+.. Purpose: The root document of the project, which serves as welcome page and contains the root
+.. of the "table of contents tree" (or toctree).
+
+PyONCatQt Documentation
+=======================
+
+PyONCatQt is a Python package designed to provide a Qt-based GUI for authentication
+and connection to the ONCat service, a data cataloging and management system developed
+by Oak Ridge National Laboratory. It serves as a plugin for other applications,
+offering a convenient PyQt-based GUI component,
+ONCatLoginDialog, for securely inputting login credentials. Upon successful authentication,
+the package establishes a connection to the ONCat service, granting access to various data
+management functionalities. PyONCatQt aims to streamline the login process and enhance user
+experience when interacting with ONCat within Python applications.
+
+Getting Started
+---------------
+Install instructions coming soon.
+
+
+.. note::
+
+   This project is under active development.
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   reference
+   sample

docs/source/reference.rst

@@ -0,0 +1,48 @@
+Reference
+=========
+
+PyONCatQt
+---------
+
+.. module:: PyONCatQt
+.. automodule:: pyoncatqt.pyoncatqt
+    :members:
+
+ONCatLoginDialog
+----------------
+
+.. module:: ONCatLoginDialog
+.. automodule:: pyoncatqt.login.ONCatLoginDialog
+    :members:
+
+ONCatLogin
+----------
+
+.. module:: ONCatLogin
+.. automodule:: pyoncatqt.login.ONCatLogin
+    :members:
+
+
+.. .. automodule:: garnet.home.view
+..     :members:
+
+.. .. automodule:: garnet.home.model
+..     :members:
+
+
+.. Base Qt Objects
+.. ---------------
+.. .. automodule:: garnet.helpers.ui_elements.base_lineedit
+..     :members:
+
+.. .. automodule:: garnet.helpers.ui_elements.base_statusbar
+..     :members:
+
+.. .. automodule:: garnet.helpers.ui_elements.base_tablewidget
+..     :members:
+
+.. .. automodule:: garnet.helpers.ui_elements.base_checkbox
+..     :members:
+
+.. .. automodule:: garnet.helpers.ui_elements.base_listwidget
+..     :members:

docs/source/sample.rst

@@ -0,0 +1,106 @@
+Sample Usage
+============
+
+ONCatLoginDialog
+----------------
+The following is a simple example of how to This example demonstrates how to
+integrate the `ONCatLoginDialog` into a PyQt application.
+
+- The application consists of a single button labeled "Login to ONCat".
+- When the button is clicked, it triggers the opening of the `ONCatLoginDialog`,
+  allowing the user to input their ONCat login credentials securely.
+- Upon successful login, the dialog closes, and the application can proceed with its functionality,
+  utilizing the authenticated ONCat connection for data management tasks.
+
+.. code:: python
+
+    class MainWindow(QWidget):
+        def __init__(self):
+            super().__init__()
+            self.initUI()
+
+        def initUI(self):
+            layout = QVBoxLayout()
+
+            # Create a button to open the ONCat login dialog
+            self.login_button = QPushButton("Login to ONCat")
+            self.login_button.clicked.connect(self.open_oncat_login_dialog)
+            layout.addWidget(self.login_button)
+            self.setLayout(layout)
+            self.setWindowTitle("ONCat Login Example")
+
+            # Create an instance of the pyoncat agent pyoncat.ONCat
+            self.agent = pyoncat.ONCat(
+                self.oncat_url,
+                client_id=self.client_id,
+                # Pass in token getter/setter callbacks here:
+                token_getter=self.read_token,
+                token_setter=self.write_token,
+                flow=pyoncat.RESOURCE_OWNER_CREDENTIALS_FLOW,
+            )
+
+        def open_oncat_login_dialog(self):
+            dialog = ONCatLoginDialog(agent=self.agent, parent=self)
+            dialog.exec_()
+
+    if __name__ == "__main__":
+        app = QApplication(sys.argv)
+        window = MainWindow()
+        window.show()
+        sys.exit(app.exec_())
+
+ONCatLogin Widget
+-----------------
+The following is a simple example of how to use the ONCatLogin widget in a PyQt application.
+This example creates a main window with an ONCatLogin widget and two QListWidgets to display
+the instrument lists for the SNS and HFIR facilities. The instrument lists are updated when
+the connection status changes.
+
+.. code:: python
+
+    class MainWindow(QWidget):
+    def __init__(self):
+        super().__init__()
+        self.initUI()
+
+    def initUI(self):
+        layout = QVBoxLayout()
+
+        # Create and add the Oncat widget
+        self.oncat_widget = ONCatLogin(key="", parent=self)
+        self.oncat_widget.connection_updated.connect(self.update_instrument_lists)
+        layout.addWidget(self.oncat_widget)
+
+        # Add list widgets for the instrument lists
+        self.sns_list = QListWidget()
+        self.hfir_list = QListWidget()
+
+        layout.addWidget(QLabel("SNS Instruments:"))
+        layout.addWidget(self.sns_list)
+        layout.addWidget(QLabel("HFIR Instruments:"))
+        layout.addWidget(self.hfir_list)
+
+        self.setLayout(layout)
+        self.setWindowTitle("ONCat Application")
+        self.oncat_widget.update_connection_status()
+
+    def update_instrument_lists(self, is_connected):
+        """Update the contents of the instrument lists based on the connection status."""
+        self.sns_list.clear()
+        self.hfir_list.clear()
+
+        if is_connected:
+            sns_instruments = self.oncat_widget.agent.Instrument.list(facility="SNS")
+            hfir_instruments = self.oncat_widget.agent.Instrument.list(facility="HFIR")
+
+            for instrument in sns_instruments:
+                self.sns_list.addItem(instrument.get("name"))
+
+            for instrument in hfir_instruments:
+                self.hfir_list.addItem(instrument.get("name"))
+
+    if __name__ == "__main__":
+        app = QApplication(sys.argv)
+        window = MainWindow()
+        window.show()
+        sys.exit(app.exec_())

pyproject.toml

@@ -55,6 +55,6 @@ line-length = 120
 
 [tool.ruff.lint]
 # https://beta.ruff.rs/docs/rules/
-select = ["A", "ARG", "BLE", "E", "F", "I", "PT"]
+select = ["A", "ARG", "BLE", "E", "F", "I", "PT", "ANN"]
 ignore = ["F403", "F405", "F401", # wild imports and  unknown names
 ]

src/pyoncatqt/__init__.py

@@ -3,12 +3,12 @@
 """
 
 try:
-    from ._version import __version__  # noqa: F401
+    from ._version import __version__  # noqa F401
 except ImportError:
     __version__ = "unknown"
 
 
-def PyONCatQt():
+def PyONCatQt():  # noqa ANN201
     """This is needed for backward compatibility because mantid workbench does "from shiver import Shiver" """
     from .pyoncatqt import PyONCatQt as pyoncatqt
 

src/pyoncatqt/configuration.py

@@ -7,7 +7,7 @@
 CONFIG_PATH_FILE = "src/pyoncatqt/configuration.ini"
 
 
-def get_data(section, name=None):
+def get_data(section: str, name: str = None) -> dict | str | bool | None:
     """retrieves the configuration data for a variable with name"""
     # default file path location
     config_file_path = CONFIG_PATH_FILE