feat(cli): Add a CLI to translate VisualizationSets to VTK

This will be helpful for debugging cases where we need to determine if the issue is in ladybug-display or ladybug-vtk.

The commit also adds tests for Python 10 and updates the Sphinx documentation so that the search feature works.

.github/workflows/ci.yaml

@@ -9,7 +9,7 @@ jobs:
     name: Unit tests
     strategy:
       matrix:
-        python-version: [3.7]
+        python-version: ['3.7', '3.10']
         os: [macos-latest, ubuntu-latest, windows-latest]
 
     runs-on: ${{ matrix.os }}

dev-requirements.txt

@@ -1,13 +1,13 @@
 pytest==6.2.4
-Sphinx==3.3.1
+Sphinx==5.3.0
 docutils==0.17
 sphinx-bootstrap-theme==0.8.1
 sphinxcontrib-fulltoc==1.2.0
 sphinxcontrib-websupport==1.2.4
-sphinx-click==2.7.1
+sphinx-click==4.4.0
 twine==3.4.1
-wheel==0.36.2
-setuptools==57.0.0
-importlib-metadata==4.3.1
+wheel==0.38.1
+setuptools==65.5.1
+importlib-metadata==4.8.0
 jinja2==3.0.3
 markupsafe==2.0.1

docs/_static/custom.css

@@ -14,6 +14,14 @@
   .bs-sidenav .nav > .active > ul {
     display: block;
   }
+  div.bs-sidenav ul {
+    margin-bottom: 0;
+    padding-left: 5px;
+    list-style: none;
+  }
+  div.bs-sidenav a {
+    color: #333333;
+  }
   /* Widen the fixed sidenav */
   .bs-sidenav.affix,
   .bs-sidenav.affix-bottom {

ladybug_vtk/__main__.py

@@ -0,0 +1,4 @@
+from ladybug_vtk.cli import vtk
+
+if __name__ == '__main__':
+    vtk()

ladybug_vtk/cli/__init__.py

@@ -0,0 +1,58 @@
+"""ladybug-vtk commands."""
+import click
+import sys
+import os
+import logging
+
+from ladybug_display.visualization import VisualizationSet
+from ladybug.cli import main
+
+_logger = logging.getLogger(__name__)
+
+
+# command group for all vtk extension commands.
+@click.group(help='ladybug VTK commands.')
+@click.version_option()
+def vtk():
+    pass
+
+
+@vtk.command('vis-to-vtk')
+@click.argument('vis-file', type=click.Path(
+    exists=True, file_okay=True, dir_okay=False, resolve_path=True))
+@click.option(
+    '--output-format', '-of', help='Text for the output format of the resulting '
+    'file. Choose from: vtkjs, html. Note that the html format refers to a web page '
+    'with the vtkjs file embedded within it. ',
+    type=str, default='vtkjs', show_default=True)
+@click.option(
+    '--output-file', help='File to output the result. Default: vis_set',
+    type=click.File('w'), default='vis_set', show_default=True)
+def vis_set_to_vtk(vis_file, output_format, output_file):
+    """Translate a VisualizationSet file (.vsf) to VTK formats.
+
+    \b
+    Args:
+        vis_file: Full path to a Ladybug Display Visualization Set (VSF) file.
+    """
+    try:
+        vis_set = VisualizationSet.from_file(vis_file)
+        output_format = output_format.lower()
+        out_folder, out_file = os.path.split(output_file.name)
+        if out_file.endswith('.vtkjs'):
+            out_file = out_file[:-6]
+        elif out_file.endswith('.html'):
+            out_file = out_file[:-5]
+        if output_format == 'vtkjs':
+            vis_set.to_vtkjs(output_folder=out_folder, file_name=out_file)
+        if output_format == 'html':
+            vis_set.to_html(output_folder=out_folder, file_name=out_file)
+    except Exception as e:
+        _logger.exception('Failed to translate VisualizationSet to VTK.\n{}'.format(e))
+        sys.exit(1)
+    else:
+        sys.exit(0)
+
+
+# add vtk sub-group to ladybug CLI
+main.add_command(vtk)

tests/cli_test.py

@@ -0,0 +1,25 @@
+"""Test cli."""
+import os
+from click.testing import CliRunner
+
+from ladybug_vtk.cli import vis_set_to_vtk
+
+
+def test_vis_set_to_vtk():
+    """Test the vis_set_to_vtk command."""
+    runner = CliRunner()
+    input_vsf = './tests/assets/daylight_factor.vsf'
+    output_vtkjs = './tests/assets/daylight_factor.vtkjs'
+    output_html = './tests/assets/daylight_factor.html'
+
+    in_args = [input_vsf, '--output-format', 'vtkjs', '--output-file', output_vtkjs]
+    result = runner.invoke(vis_set_to_vtk, in_args)
+    assert result.exit_code == 0
+    assert os.path.isfile(output_vtkjs)
+    os.remove(output_vtkjs)
+
+    in_args = [input_vsf, '--output-format', 'html', '--output-file', output_html]
+    result = runner.invoke(vis_set_to_vtk, in_args)
+    assert result.exit_code == 0
+    assert os.path.isfile(output_html)
+    os.remove(output_html)