Merge pull request #4 from NWChemEx/initial2

Sphinx auto docs and html

.github/.licenserc.yaml

@@ -24,5 +24,6 @@ header:
     - docs/requirements.txt
     - docs/source/bibliography/*.bib
     - plugin_player_setup.kv
+    - docs/source/nitpick_exceptions
 
   comment: never

.github/workflows/merge.yaml

@@ -0,0 +1,29 @@
+# Copyright 2023 NWChemEx-Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+name: .github Merge Workflow
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  Common-Merge:
+    uses: NWChemEx/.github/.github/workflows/common_merge.yaml@master
+    with:
+      doc_target: 'Sphinx'
+      generate_module_docs: false
+    secrets: inherit

.github/workflows/pull_request.yaml

@@ -27,5 +27,5 @@ jobs:
       config_file: '.github/.licenserc.yaml'
       source_dir: ''
       compilers: ''
-      doc_target: ''
+      doc_target: 'sphinx'
     secrets: inherit

docs/source/conf.py

@@ -43,12 +43,9 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.doctest',
-    'sphinx.ext.todo',
-    'sphinx.ext.coverage',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.githubpages',
-    # 'autoapi.extension'
+    'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.coverage',
+    'sphinx.ext.mathjax', 'sphinx.ext.githubpages', 'sphinx.ext.autodoc',
+    'autoapi.extension'
 ]
 dir_path = os.path.dirname(os.path.realpath(__file__))
 doc_path = os.path.dirname(dir_path)
@@ -163,19 +160,14 @@
 ]
 
 # -- Extension configuration -------------------------------------------------
-# autoapi_dirs = [
-#     '../../src',
-# ]
-# autoapi_add_toctree_entry = False
-# autoapi_options = [
-#     'members',
-#     'undoc-members',
-#     'private-members',
-#     'show-inheritance',
-#     'show-module-summary',
-#     'special-members',
-#     #    'imported-members',
-# ]
+autoapi_dirs = [
+    '../../src/pluginplayer',
+]
+autoapi_add_toctree_entry = True
+autoapi_options = [
+    'members', 'undoc-members', 'private-members', 'show-module-summary',
+    'special-members'
+]
 
 # -- Options for intersphinx extension ---------------------------------------
 
@@ -186,3 +178,15 @@
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
+
+# -- Nitpick Ignore options --------------------------------------------------
+
+# Nitpick requires all references to be resolved
+# This will ignore those that references that can't be linked
+nitpick_ignore = []
+with open('nitpick_exceptions') as f:
+    for line in f:
+        line = line.strip()
+        if line and not line.startswith("#"):
+            dtype, target = line.split(None, 1)
+            nitpick_ignore.append((dtype, target))

docs/source/index.rst

@@ -16,11 +16,13 @@
 PluginPlayer
 ############
 
-PluginPlayer is a :term:`GUI <GUI>` for `PluginPlay <https://github.com/NWChemEx/PluginPlay>`__.
-
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-   terminology
+   introductory
+   kivyintro
+
+   autoapi/index
+
 

docs/source/introductory.rst

@@ -0,0 +1,95 @@
+.. Copyright 2024 NWChemEx-Project
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+#############################
+Introductary Observations
+#############################
+
+
+
+
+Modular-based Software
+
+    Using modular software in a project requires running collections of Modules in a series, 
+    which are uniquely connected based on the user’s application needs. 
+    Module collections are written in Plugins, which hold Modules with related 
+    functionality and topics. Each Module has defined inputs, outputs, and submodules, 
+    which define its property type and API to run correctly. 
+
+    To run a Module, it must be imported into the ModuleManger, 
+    which handles selecting Submodules and inputs to run the Module successfully. 
+    When creating a complete modular program, the aim is to connect multiple Modules together, 
+    using outputs from one Module as inputs for another. This requires the user to load each 
+    Plugin’s Module collection into a ModuleManager manually, configure the Submodules, 
+    and run each Module individually, storing a Module’s outputs to place as future inputs 
+    for another Module.
+
+An Alternative Solution: GUI Goals
+
+    Using modular software as an approach allows separation between working units in a 
+    complete application design but requires extensive writing of each application run 
+    to import, link, and run modules in a series. The main goal of creating a Graphical 
+    User Interface for a PluginPlay modular software application is to allow a user or 
+    developer to select compiled plugins and create an application tree that connects 
+    Modules’ outputs and inputs to run in a desired series. This can reduce a user's 
+    or developer’s time testing an application using modular components. 
+
+Using Kivy, Why?
+    When designing a modular software user interface, we must note our objectives and choose 
+    a visual library that suits the project’s needs. The main goal of this user interface is 
+    to provide both users and developers with an application with a modern, simplistic, and 
+    reliable design to build and view a custom visual tree-like structure of connected Modules. 
+    This application should be functional on multiple platforms, as users have different 
+    operating systems and screen proportions.
+
+    Tkinter is a popular Python GUI-building library that can build objects, buttons, and 
+    visual displays from the standard Python library. Tkinter runs on MacOS and Windows 
+    systems and can be implemented into a website as a Python app. However, Tkinter has 
+    limited “Canvas” functionality, limiting the number of widgets placed in a particular 
+    area and varying designs from platform to platform. With adding a custom amount of Plugin 
+    folders and listing Modules, Tkinter lacks the ease of organizing these objects in a frame. 
+    Tkinter also manages mouse events complexly, limiting drag-and-drop functionality, which 
+    is essential when maneuvering Modules into a custom tree-like structure. However, as Tkinter 
+    is a standard python library, external third-party libraries are available to overcome some 
+    limitations.
+
+    PyQt is a set of Python bindings for a Qt application framework. PyQt provides a wide range 
+    of customizable widgets, making it suitable for creating complex user interfaces, including 
+    trees with various elements. PyQt offers a native look and feel on different platforms, 
+    ensuring an application's GUI is consistent across Windows, macOS, and Linux. PyQt has a 
+    steeper learning curve than more straightforward GUI frameworks like Tkinter, especially 
+    for beginners. Understanding the Qt framework's concepts and PyQt-specific features may 
+    take some time. The ability to change and modify the PluginPlay GUI framework is essential, 
+    and a learning obstacle will make it difficult for editor alterations.
+
+    Kivy is a versatile open-source Python framework for developing cross-platform applications,
+    including those with custom GUI components like a tree structure with draggable widgets. 
+    Kivy supports multiple platforms, including Windows, macOS, Linux, Android, and iOS, allowing 
+    you to create applications that run on various devices. Supporting multiple platforms, including 
+    mobile devices, allows the implementation of the GUI to branch to a mobile application. Kivy is 
+    designed for touch interfaces, making it suitable for multitouch and gesture support applications. 
+    This can be beneficial for interactive and touch-based interfaces. While you can use any Python 
+    IDE with Kivy, the level of support might not be as extensive as for some other GUI frameworks. 
+    However, there is extensive community support for Kivy and well-defined documentation that can 
+    allow collaboration and easier editing of the GUI.
+
+    Kivy was chosen as the Python library to build the PluginPlay GUI for its easy-to-use design 
+    and assortment of widgets that can be moved with drag-and-drop manipulation to create a custom 
+    Module tree design. The compatibility with multiple platforms and mobile devices makes Kivy a 
+    versatile tool that can work on various devices.
+
+
+
+
+

docs/source/kivyintro.rst

@@ -0,0 +1,81 @@
+.. Copyright 2024 NWChemEx-Project
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+#############################
+Kivy
+#############################
+
+Windows and Kivy Structures
+===========================
+    In Kivy, a Window serves as the main drawing area for your application. It is the top-level container that encompasses the entire graphical space. You can customize the window's properties, such as its size, title, and fullscreen mode. Additionally, Kivy supports multiple windows, allowing for more complex application structures.
+
+    The primary building blocks of the user interface in Kivy are Widgets. Widgets are graphical elements that can be added to windows to create interactive user interfaces. Kivy provides a wide range of predefined widgets, including buttons, labels, text inputs, and more. Widgets can be arranged and nested in various layouts to achieve the desired user interface design. They handle user input events, such as touch or mouse interactions, and can be styled and customized to fit the application's visual theme. Understanding the structure of Windows and Widgets is fundamental to creating dynamic and responsive user interfaces in Kivy.
+
+Widget Types
+============
+    BoxLayout
+        The `BoxLayout` widget in Kivy is a versatile layout manager that simplifies the 
+        arrangement of child widgets either horizontally or vertically. With its `orientation` 
+        property, developers can easily create rows or columns of widgets. The automatic sizing 
+        of children based on available space makes it convenient for creating dynamic interfaces 
+        that adapt to various screen sizes.
+
+    Image
+        Kivy's `Image` widget is a powerful tool for displaying graphical content within 
+        applications. It supports a variety of image formats and provides features for 
+        manipulating and presenting images, including scaling and rotation. This widget is 
+        crucial for incorporating visual elements and enhancing the aesthetic appeal of Kivy 
+        applications.
+
+    Widget
+        The `Widget` class serves as the fundamental building block for all other widgets in Kivy. 
+        It offers a container for housing other widgets, providing essential properties and methods. 
+        Developers can either use it as a generic container or subclass it to create custom widgets 
+        with specific behaviors and functionalities.
+
+    Button
+        The `Button` widget is a fundamental component for creating interactive user interfaces in 
+        Kivy applications. It represents a clickable element that can trigger predefined actions or 
+        functions when pressed. Buttons are commonly employed for user-initiated actions, such as 
+        submitting forms or navigating between different sections of an application.
+
+    TextInput
+        The `TextInput` widget facilitates the input and display of multiline text in Kivy 
+        applications. It supports keyboard input and can be customized for various text-related 
+        functionalities, such as password masking or restricting input to numeric values. This 
+        widget is essential for capturing user-generated textual content.
+
+    Line
+        Kivy's `Line` widget is a powerful tool for drawing lines and shapes within an application. 
+        It enables developers to create custom graphics and diagrams, allowing for enhanced 
+        visualization and artistic expression in the user interface.
+
+    Popup
+        The `Popup` widget is a versatile tool for displaying temporary and context-specific 
+        information in Kivy applications. Whether used for alerts, notifications, or additional 
+        user input, the `Popup` widget creates a separate window that can be modal or non-modal, 
+        enhancing the user experience by providing focused interactions.
+
+    Label
+        The `Label` widget in Kivy is essential for presenting textual information in the user 
+        interface. It supports various text formatting options and serves as a straightforward yet 
+        powerful means of conveying information, titles, or instructions within the application.
+
+    ScrollView
+        The `ScrollView` widget is indispensable when dealing with content that exceeds the 
+        available screen space. It enables users to scroll through content, ensuring that all 
+        information remains accessible. This widget is particularly useful for presenting lengthy 
+        text, images, or other types of data without cluttering the main screen.
+
+    `Kivy Documentation <https://kivy.org/doc/stable/>`_

docs/source/nitpick_exceptions

@@ -0,0 +1,7 @@
+py:class kivy.uix.button.Button
+py:class kivy.uix.behaviors.ButtonBehavior
+py:class kivy.uix.boxlayout.BoxLayout
+py:class kivy.core.window.Event
+py:class kivy.app.App
+py:class kivy.uix.widget.Widget
+py:class kivy.uix.relativelayout.RelativeLayout

requirements.txt

@@ -0,0 +1,2 @@
+kivy
+Pillow

src/pluginplayer/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2024 NWChemEx-Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

node_manager.py → src/pluginplayer/node_manager.py

@@ -11,7 +11,11 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""
+Linking a connection
+    The Set input/submodule popup shows each module from each imported plugin and shows a “Set” button to set it as the input or submodule. On clicking a “Set” button, the ModuleManager will attempt to set it to the run settings using the `link_input`, `link_property_type`, or `link_submod` functions within the `NodeManager` class. If it succeeds, it will be set in the node’s run settings with its description and the connected node’s information. If an error occurs, a message will output the error, and no settings will be set.
 
+"""
 #kivy helpers
 from kivy.graphics import Line
 from kivy.uix.widget import Widget