[#156] Created pydocs documentation for the gv_ui modules (#186)

cs481-ekh · Apr 19, 2024 · 3ae5d25 · 3ae5d25
1 parent a0518e0
commit 3ae5d25
Show file tree

Hide file tree

Showing 10 changed files with 369 additions and 10 deletions.
diff --git a/GoVizzy/gv_ui/gv_ui/DisplayUI.py b/GoVizzy/gv_ui/gv_ui/DisplayUI.py
@@ -1,3 +1,7 @@
+"""
+This module provides functionality to display output widgets for GoVizzy.
+"""
+
 import ipywidgets as widgets
 from ipywidgets import Dropdown, VBox, HBox, Output, ColorPicker, AppLayout, Layout, Label, Button, Checkbox, link, Accordion
 import ipyvolume as ipv
@@ -24,8 +28,11 @@
 # atom mesh globals
 atom_meshes = []
 
-# Displays logo and hides the app output
 def show_menu():
+    """
+    Displays logo and hides the app output.
+    """
+
     exit_button.layout.visibility = 'visible'
     selected_view_options.layout.visibility = 'hidden'
     dropdown.layout.visibility = 'hidden'
@@ -46,7 +53,10 @@ def show_menu():
    # display_app()
 
 def show_ui():
-
+    """
+    Sets the visibility of the GoVizzy output widgets to visible.
+    """
+
     large_box.layout.visibility = 'visible'
     selected_view_options.layout.visibility = 'visible'
     dropdown.layout.visibility = 'visible'
@@ -55,6 +65,10 @@ def show_ui():
     newCube_button.layout.visibility = 'visible'
 
 def display_cube(cube):
+    """
+    Displays the cube plot based on the value of the dropdown.
+    """
+
     global atom_meshes
     visualizer = plotting.Visualizer(cube)
     with large_box:  # Capture output within large_box
@@ -82,7 +96,10 @@ def display_cube(cube):
 
 
 def display_app():
-
+    """
+    Displays the ipvolume.Figure and sets the sidebar options.
+    """
+
     # Containers for right menu 
     global atom_meshes
 
@@ -151,6 +168,10 @@ def display_app():
 
 
 def clear_all_outputs():
+    """
+    Clears the output of the GoVizzy widgets and sets their visibilities to 
+    hidden.
+    """
     large_box.clear_output()
     selected_view_options.clear_output()
     slice_picker.clear_output()
@@ -168,6 +189,10 @@ def clear_all_outputs():
         display(exit_message)
 
 def handle_dropdown_change(change, cube):
+    """
+    Sets the selected option to the value of the dropdown.
+    """
+
     global selected_option
     selected_option = change.new
 

diff --git a/GoVizzy/gv_ui/gv_ui/fileInput.py b/GoVizzy/gv_ui/gv_ui/fileInput.py
@@ -7,7 +7,12 @@
 
 # Function to find the source file path based on the file name
 def find_source_path(fileName, directory):
-
+    """
+    Given a filename and a directory, it traverses down the directory to find
+    a matching file. If the file exists it returns the file path, otherwise it
+    returns None.
+    """
+
     for root, dirs, files in os.walk(directory):
         if fileName in files:
             # Return the full path of the file
@@ -18,6 +23,11 @@ def find_source_path(fileName, directory):
 
 # Function to generate a unique file name with an ascending number
 def generate_unique_filename(fileName, directory):
+    """
+    Given a path to a file, it creates a new file at the provided directory
+    with a unique number appended to the end.
+    """
+
     # If the file already exists in the destination directory, append an ascending number
     counter = 1
     while True:
@@ -34,6 +44,12 @@ def generate_unique_filename(fileName, directory):
 
 # Function to copy a file from source to destination
 def copy_file(source_path, destination_path):
+    """
+    Given the source path and destination path, it copies the file from the
+    source path to the destination path. Returns True if the copy is successful
+    otherwise False.
+    """
+
     try:
         # Copy the file from source to destination
         shutil.copyfile(source_path, destination_path)

diff --git a/GoVizzy/gv_ui/gv_ui/gvWidgets.py b/GoVizzy/gv_ui/gv_ui/gvWidgets.py
@@ -89,19 +89,34 @@
 )
 
 def mesh_visibility_toggle(mesh: Mesh, description: str="Atom"):
+    """
+    Returns an ipywidget.Checkbox with the provided description and links the
+    value to the provided mesh visibility.
+    """
+
     toggle = Checkbox(value=True, description=description)
     link((toggle, 'value'), (mesh, 'visible'))
     return toggle
 
 color = ColorPicker(concise=True, value='white', description='Color', disabled=False, layout=Layout(flex='1 1 0%', width='auto'))
 
 def atom_color_picker(atom: Mesh, description: str="Color"):
+    """
+    Returns an ipywidget.ColorPicker with the provided description and links the
+    value to the provided mesh color.
+    """
+
     picker = ColorPicker(value=str(atom.color), description=description)
     link((picker, 'value'), (atom, 'color'))
     return picker
 
 
 def scale_atom_mesh(atom: Mesh, points: tuple[list, list, list], origin: tuple[float, float, float], scale: float):
+    """
+    Scales the size of the original atom size by the scaling factor. Sets the
+    scaled values to the provided atom.
+    """
+
     x, y, z = points
     origin_x, origin_y, origin_z = origin
     scaled_x = (x - origin_x) * scale + origin_x
@@ -110,6 +125,11 @@ def scale_atom_mesh(atom: Mesh, points: tuple[list, list, list], origin: tuple[f
     atom.x, atom.y, atom.z = scaled_x, scaled_y, scaled_z
 
 def atom_scale_slider(atom: Mesh, description: str="Scale"):
+    """
+    Returns an ipywidget.BoundedFloatText with the provided description and
+    links the value to a function which adjusts the scale of the atom.
+    """
+
     slider = BoundedFloatText(
         value=1,
         min=0,

diff --git a/GoVizzy/gv_ui/gv_ui/meshes.py b/GoVizzy/gv_ui/gv_ui/meshes.py
@@ -54,11 +54,11 @@
 }
 
 def plot_sphere_surface(origin: tuple[int, int, int]=(0, 0, 0), radius: int=1, color: str="red"):
-    '''
+    """
     Plots on an existing ipyvolume figure the surface of a sphere. By default
     the sphere is located at the origin (0, 0, 0) with a radius of 1 and color
     "red".
-    '''
+    """
     x_origin, y_origin, z_origin = origin
     step = 0.1
     gridx, gridy = np.ix_(np.arange(0, np.pi + step, step), np.arange(0, 2 * np.pi + step, step))
@@ -74,10 +74,10 @@ def sphere_surface(phi: float, theta: float):
     return ipv.plot_surface(x, z, y, color=color)
 
 def plot_atoms(cube: Cube, sizes: dict[int, int]=vanderwaals, colors: dict[int, str]=default_colors):
-    '''
+    """
     Plots the atoms from a provided Cube object using the sizes and colors in
     the provided dicts. The keys are the atomic number of the atoms in the cell.
-    '''
+    """
     default_color = "red"
     default_size = 10
     atom_meshes = []
@@ -90,10 +90,10 @@ def plot_atoms(cube: Cube, sizes: dict[int, int]=vanderwaals, colors: dict[int,
     return atom_meshes
 
 def plot_bonds(cube: Cube, size: int=3., color: int="black"):
-    '''
+    """
     Plots the bonds between atoms in the current Cube object, using the list of atom pairs, 
     and the positions of the atoms in the graph.
-    '''
+    """
     cube.get_bonds()
     num_pts = 1000
 

diff --git a/docs/gv_ui/gv_ui.DisplayUI.html b/docs/gv_ui/gv_ui.DisplayUI.html
@@ -0,0 +1,59 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Python: module gv_ui.DisplayUI</title>
+</head><body>
+
+<table class="heading">
+<tr class="heading-text decor">
+<td class="title">&nbsp;<br><strong class="title"><a href="gv_ui.html" class="white">gv_ui</a>.DisplayUI</strong></td>
+<td class="extra"><a href=".">index</a><br><a href="../../GoVizzy/gv_ui/gv_ui/DisplayUI.py">gv_ui/gv_ui/DisplayUI.py</a></td></tr></table>
+    <p><span class="code">This&nbsp;module&nbsp;provides&nbsp;functionality&nbsp;to&nbsp;display&nbsp;output&nbsp;widgets&nbsp;for&nbsp;GoVizzy.</span></p>
+<p>
+<table class="section">
+<tr class="decor pkg-content-decor heading-text">
+<td class="section-title" colspan=3>&nbsp;<br><strong class="bigsection">Modules</strong></td></tr>
+
+<tr><td class="decor pkg-content-decor"><span class="code">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></td><td>&nbsp;</td>
+<td class="singlecolumn"><table><tr><td class="multicolumn"><a href="gv_ui.gvWidgets.html">gv_ui.gvWidgets</a><br>
+ipyvolume<br>
+</td><td class="multicolumn"><a href="gv_ui.meshes.html">gv_ui.meshes</a><br>
+<a href="gv_ui.plotting.html">gv_ui.plotting</a><br>
+</td><td class="multicolumn">matplotlib.pyplot<br>
+ipywidgets<br>
+</td><td class="multicolumn"></td></tr></table></td></tr></table><p>
+<table class="section">
+<tr class="decor functions-decor heading-text">
+<td class="section-title" colspan=3>&nbsp;<br><strong class="bigsection">Functions</strong></td></tr>
+
+<tr><td class="decor functions-decor"><span class="code">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></td><td>&nbsp;</td>
+<td class="singlecolumn"><dl><dt><a name="-clear_all_outputs"><strong>clear_all_outputs</strong></a>()</dt><dd><span class="code">Clears&nbsp;the&nbsp;output&nbsp;of&nbsp;the&nbsp;GoVizzy&nbsp;widgets&nbsp;and&nbsp;sets&nbsp;their&nbsp;visibilities&nbsp;to&nbsp;<br>
+hidden.</span></dd></dl>
+ <dl><dt><a name="-display_app"><strong>display_app</strong></a>()</dt><dd><span class="code">Displays&nbsp;the&nbsp;ipvolume.Figure&nbsp;and&nbsp;sets&nbsp;the&nbsp;sidebar&nbsp;options.</span></dd></dl>
+ <dl><dt><a name="-display_cube"><strong>display_cube</strong></a>(cube)</dt><dd><span class="code">Displays&nbsp;the&nbsp;cube&nbsp;plot&nbsp;based&nbsp;on&nbsp;the&nbsp;value&nbsp;of&nbsp;the&nbsp;dropdown.</span></dd></dl>
+ <dl><dt><a name="-handle_dropdown_change"><strong>handle_dropdown_change</strong></a>(change, cube)</dt><dd><span class="code">Sets&nbsp;the&nbsp;selected&nbsp;option&nbsp;to&nbsp;the&nbsp;value&nbsp;of&nbsp;the&nbsp;dropdown.</span></dd></dl>
+ <dl><dt><a name="-show_menu"><strong>show_menu</strong></a>()</dt><dd><span class="code">Displays&nbsp;logo&nbsp;and&nbsp;hides&nbsp;the&nbsp;app&nbsp;output.</span></dd></dl>
+ <dl><dt><a name="-show_ui"><strong>show_ui</strong></a>()</dt><dd><span class="code">Sets&nbsp;the&nbsp;visibility&nbsp;of&nbsp;the&nbsp;GoVizzy&nbsp;output&nbsp;widgets&nbsp;to&nbsp;visible.</span></dd></dl>
+</td></tr></table><p>
+<table class="section">
+<tr class="decor data-decor heading-text">
+<td class="section-title" colspan=3>&nbsp;<br><strong class="bigsection">Data</strong></td></tr>
+
+<tr><td class="decor data-decor"><span class="code">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></td><td>&nbsp;</td>
+<td class="singlecolumn"><strong>atom_meshes</strong> = []<br>
+<strong>bond_color_picker</strong> = ColorPicker(value='black', description='Bond Color')<br>
+<strong>bond_scale_slider</strong> = BoundedFloatText(value=3.0, description='Bond Scale', max=10.0, step=0.01)<br>
+<strong>bond_visibility_toggle</strong> = Checkbox(value=True, description='Bond Visibility')<br>
+<strong>dropdown</strong> = Dropdown(layout=Layout(margin='5px 0 0 5px'), op...Options', 'Mesh Options'), value='Slice Options')<br>
+<strong>exit_button</strong> = Button(button_style='danger', description='[X]',...Layout(margin='0 0 0 auto'), style=ButtonStyle())<br>
+<strong>in_app_exit</strong> = Button(button_style='danger', description='[X]', style=ButtonStyle())<br>
+<strong>large_box</strong> = Output(layout=Layout(height='100%', width='70%'))<br>
+<strong>newCube_button</strong> = Button(description='New Cube', layout=Layout(bor...1px solid black', flex='1'), style=ButtonStyle())<br>
+<strong>options</strong> = ['Slice Options', 'Mesh Options']<br>
+<strong>save_button</strong> = Button(description='Save', layout=Layout(border_...1px solid black', flex='1'), style=ButtonStyle())<br>
+<strong>selected_option</strong> = 'Slice Options'<br>
+<strong>selected_view_options</strong> = Output(layout=Layout(height='300px', width='auto'))<br>
+<strong>slice_picker</strong> = Output(layout=Layout(border_bottom='1px solid bl... black', border_top='1px solid black', flex='1'))<br>
+<strong>slice_picker_descr</strong> = Label(value='Slice Picker', layout=Layout(margin='5px 0 0 5px'))</td></tr></table>
+</body></html>
diff --git a/docs/gv_ui/gv_ui.fileInput.html b/docs/gv_ui/gv_ui.fileInput.html
@@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Python: module gv_ui.fileInput</title>
+</head><body>
+
+<table class="heading">
+<tr class="heading-text decor">
+<td class="title">&nbsp;<br><strong class="title"><a href="gv_ui.html" class="white">gv_ui</a>.fileInput</strong></td>
+<td class="extra"><a href=".">index</a><br><a href="../../GoVizzy/gv_ui/gv_ui/fileInput.py">gv_ui/gv_ui/fileInput.py</a></td></tr></table>
+    <p></p>
+<p>
+<table class="section">
+<tr class="decor pkg-content-decor heading-text">
+<td class="section-title" colspan=3>&nbsp;<br><strong class="bigsection">Modules</strong></td></tr>
+
+<tr><td class="decor pkg-content-decor"><span class="code">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></td><td>&nbsp;</td>
+<td class="singlecolumn"><table><tr><td class="multicolumn">cube_viskit<br>
+numpy<br>
+</td><td class="multicolumn">os<br>
+matplotlib.pyplot<br>
+</td><td class="multicolumn">shutil<br>
+</td><td class="multicolumn"></td></tr></table></td></tr></table><p>
+<table class="section">
+<tr class="decor functions-decor heading-text">
+<td class="section-title" colspan=3>&nbsp;<br><strong class="bigsection">Functions</strong></td></tr>
+
+<tr><td class="decor functions-decor"><span class="code">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></td><td>&nbsp;</td>
+<td class="singlecolumn"><dl><dt><a name="-copy_file"><strong>copy_file</strong></a>(source_path, destination_path)</dt><dd><span class="code">Given&nbsp;the&nbsp;source&nbsp;path&nbsp;and&nbsp;destination&nbsp;path,&nbsp;it&nbsp;copies&nbsp;the&nbsp;file&nbsp;from&nbsp;the<br>
+source&nbsp;path&nbsp;to&nbsp;the&nbsp;destination&nbsp;path.&nbsp;Returns&nbsp;True&nbsp;if&nbsp;the&nbsp;copy&nbsp;is&nbsp;successful<br>
+otherwise&nbsp;False.</span></dd></dl>
+ <dl><dt><a name="-find_source_path"><strong>find_source_path</strong></a>(fileName, directory)</dt><dd><span class="code">Given&nbsp;a&nbsp;filename&nbsp;and&nbsp;a&nbsp;directory,&nbsp;it&nbsp;traverses&nbsp;down&nbsp;the&nbsp;directory&nbsp;to&nbsp;find<br>
+a&nbsp;matching&nbsp;file.&nbsp;If&nbsp;the&nbsp;file&nbsp;exists&nbsp;it&nbsp;returns&nbsp;the&nbsp;file&nbsp;path,&nbsp;otherwise&nbsp;it<br>
+returns&nbsp;None.</span></dd></dl>
+ <dl><dt><a name="-generate_unique_filename"><strong>generate_unique_filename</strong></a>(fileName, directory)</dt><dd><span class="code">Given&nbsp;a&nbsp;path&nbsp;to&nbsp;a&nbsp;file,&nbsp;it&nbsp;creates&nbsp;a&nbsp;new&nbsp;file&nbsp;at&nbsp;the&nbsp;provided&nbsp;directory<br>
+with&nbsp;a&nbsp;unique&nbsp;number&nbsp;appended&nbsp;to&nbsp;the&nbsp;end.</span></dd></dl>
+</td></tr></table>
+</body></html>
diff --git a/docs/gv_ui/gv_ui.gvWidgets.html b/docs/gv_ui/gv_ui.gvWidgets.html
@@ -0,0 +1,55 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Python: module gv_ui.gvWidgets</title>
+</head><body>
+
+<table class="heading">
+<tr class="heading-text decor">
+<td class="title">&nbsp;<br><strong class="title"><a href="gv_ui.html" class="white">gv_ui</a>.gvWidgets</strong></td>
+<td class="extra"><a href=".">index</a><br><a href="../../GoVizzy/gv_ui/gv_ui/gvWidgets.py">gv_ui/gv_ui/gvWidgets.py</a></td></tr></table>
+    <p><span class="code">This&nbsp;File&nbsp;is&nbsp;for&nbsp;widgets&nbsp;used&nbsp;by&nbsp;GoVizzy<br>
+Input&nbsp;form:&nbsp;widget&nbsp;for&nbsp;uploading&nbsp;a&nbsp;.cube&nbsp;file<br>
+Documentation&nbsp;for&nbsp;widget&nbsp;library:&nbsp;<a href="https://ipywidgets.readthedocs.io/en/latest/examples/Widget%20List.html#file-upload">https://ipywidgets.readthedocs.io/en/latest/examples/Widget%20List.html#file-upload</a></span></p>
+<p>
+<table class="section">
+<tr class="decor pkg-content-decor heading-text">
+<td class="section-title" colspan=3>&nbsp;<br><strong class="bigsection">Modules</strong></td></tr>
+
+<tr><td class="decor pkg-content-decor"><span class="code">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></td><td>&nbsp;</td>
+<td class="singlecolumn"><table><tr><td class="multicolumn">numpy<br>
+</td><td class="multicolumn"></td><td class="multicolumn"></td><td class="multicolumn"></td></tr></table></td></tr></table><p>
+<table class="section">
+<tr class="decor functions-decor heading-text">
+<td class="section-title" colspan=3>&nbsp;<br><strong class="bigsection">Functions</strong></td></tr>
+
+<tr><td class="decor functions-decor"><span class="code">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></td><td>&nbsp;</td>
+<td class="singlecolumn"><dl><dt><a name="-atom_color_picker"><strong>atom_color_picker</strong></a>(atom: ipyvolume.widgets.Mesh, description: str = 'Color')</dt><dd><span class="code">Returns&nbsp;an&nbsp;ipywidget.ColorPicker&nbsp;with&nbsp;the&nbsp;provided&nbsp;description&nbsp;and&nbsp;links&nbsp;the<br>
+value&nbsp;to&nbsp;the&nbsp;provided&nbsp;mesh&nbsp;color.</span></dd></dl>
+ <dl><dt><a name="-atom_scale_slider"><strong>atom_scale_slider</strong></a>(atom: ipyvolume.widgets.Mesh, description: str = 'Scale')</dt><dd><span class="code">Returns&nbsp;an&nbsp;ipywidget.BoundedFloatText&nbsp;with&nbsp;the&nbsp;provided&nbsp;description&nbsp;and<br>
+links&nbsp;the&nbsp;value&nbsp;to&nbsp;a&nbsp;function&nbsp;which&nbsp;adjusts&nbsp;the&nbsp;scale&nbsp;of&nbsp;the&nbsp;atom.</span></dd></dl>
+ <dl><dt><a name="-mesh_visibility_toggle"><strong>mesh_visibility_toggle</strong></a>(mesh: ipyvolume.widgets.Mesh, description: str = 'Atom')</dt><dd><span class="code">Returns&nbsp;an&nbsp;ipywidget.Checkbox&nbsp;with&nbsp;the&nbsp;provided&nbsp;description&nbsp;and&nbsp;links&nbsp;the<br>
+value&nbsp;to&nbsp;the&nbsp;provided&nbsp;mesh&nbsp;visibility.</span></dd></dl>
+ <dl><dt><a name="-scale_atom_mesh"><strong>scale_atom_mesh</strong></a>(atom: ipyvolume.widgets.Mesh, points: tuple[list, list, list], origin: tuple[float, float, float], scale: float)</dt><dd><span class="code">Scales&nbsp;the&nbsp;size&nbsp;of&nbsp;the&nbsp;original&nbsp;atom&nbsp;size&nbsp;by&nbsp;the&nbsp;scaling&nbsp;factor.&nbsp;Sets&nbsp;the<br>
+scaled&nbsp;values&nbsp;to&nbsp;the&nbsp;provided&nbsp;atom.</span></dd></dl>
+</td></tr></table><p>
+<table class="section">
+<tr class="decor data-decor heading-text">
+<td class="section-title" colspan=3>&nbsp;<br><strong class="bigsection">Data</strong></td></tr>
+
+<tr><td class="decor data-decor"><span class="code">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></td><td>&nbsp;</td>
+<td class="singlecolumn"><strong>bond_color_picker</strong> = ColorPicker(value='black', description='Bond Color')<br>
+<strong>bond_scale_slider</strong> = BoundedFloatText(value=3.0, description='Bond Scale', max=10.0, step=0.01)<br>
+<strong>bond_visibility_toggle</strong> = Checkbox(value=True, description='Bond Visibility')<br>
+<strong>color</strong> = ColorPicker(value='white', concise=True, descrip...lor', layout=Layout(flex='1 1 0%', width='auto'))<br>
+<strong>form</strong> = Box(children=(Box(children=(Label(value='Path to...', display='flex', flex_flow='row', width='50%'))<br>
+<strong>form_item_layout</strong> = Layout(display='flex', flex_flow='row', justify_content='space-between')<br>
+<strong>form_items</strong> = [Box(children=(Label(value='Path to .cube file'),...lex_flow='row', justify_content='space-between')), ColorPicker(value='white', concise=True, descrip...lor', layout=Layout(flex='1 1 0%', width='auto')), Button(description='Submit', layout=Layout(flex='1 1 0%', width='auto'), style=ButtonStyle()), FloatSlider(value=0.0, description='X Pos', max=120.0, readout_format='.1f')]<br>
+<strong>slice_x_check</strong> = Checkbox(value=False, description='X Toggle')<br>
+<strong>slice_x_slider</strong> = FloatSlider(value=0.0, description='X Pos', max=120.0, readout_format='.1f')<br>
+<strong>slice_y_check</strong> = Checkbox(value=False, description='Y Toggle')<br>
+<strong>slice_y_slider</strong> = FloatSlider(value=0.0, description='Y Pos', max=120.0, readout_format='.1f')<br>
+<strong>slice_z_check</strong> = Checkbox(value=False, description='Z Toggle')<br>
+<strong>slice_z_slider</strong> = FloatSlider(value=0.0, description='Z Pos', max=120.0, readout_format='.1f')</td></tr></table>
+</body></html>