fix: Local launcher fixes

.gitignore

@@ -70,6 +70,8 @@ instance/
 
 # Sphinx documentation
 doc/_build/
+*sg_execution_times.rst
+doc/source/examples
 
 # PyBuilder
 .pybuilder/
@@ -131,7 +133,7 @@ celerybeat.pid
 .env
 .venv
 env/
-venv/
+*venv/
 ENV/
 env.bak/
 venv.bak/

doc/Makefile

@@ -5,7 +5,7 @@
 SPHINXOPTS    = -j auto -W --color
 SPHINXBUILD   = sphinx-build
 APIDIR        = api
-EXAMPLESDIR        = examples
+EXAMPLESDIR   = examples
 SOURCEDIR     = source
 BUILDDIR      = _build
 

doc/source/changelog/118.documentation.md

@@ -0,0 +1 @@
+Fix: Local launcher fixes

doc/source/conf.py

@@ -82,12 +82,38 @@
     "sphinx_design",
     "ansys_sphinx_theme.extension.autoapi",
     "sphinx_click",  # Required by local-product-launcher
+    "sphinx_gallery.gen_gallery",
+    "sphinx_jinja",
 ]
 
+# sphinx gallery options
+sphinx_gallery_conf = {
+    # path to your examples scripts
+    "examples_dirs": ["../../examples/local_launcher/example_scripts"],
+    # path where to save gallery generated examples
+    "gallery_dirs": ["examples"],
+    # Pattern to search for example files - match ALL .py files
+    "filename_pattern": r"\.py",
+    # Ignore pattern to exclude __init__.py
+    "ignore_pattern": "flycheck*",
+    # Remove the "Download all examples" button from the top level gallery
+    "download_all_examples": False,
+    # Sort gallery example by file name instead of number of lines (default)
+    "within_subsection_order": "FileNameSortKey",
+    # directory where function granular galleries are stored
+    "backreferences_dir": None,
+    # Modules for which function level galleries are created.
+    "doc_module": "ansys-tools-common",
+    "image_scrapers": ("matplotlib",),
+    "thumbnail_size": (350, 350),
+    "copyfile_regex": r".*\.rst",
+}
+
 # numpydoc configuration
 numpydoc_show_class_members = False
 numpydoc_xref_param_type = True
 
+
 # Consider enabling numpydoc validation. See:
 # https://numpydoc.readthedocs.io/en/latest/validation.html#
 numpydoc_validate = True

doc/source/index.rst

@@ -31,6 +31,13 @@ Ansys Common Tools provides a collection of tools for the PyAnsys ecosystem.
 
         Understand how to use Python to interact programmatically with the tools.
 
+    .. grid-item-card:: Examples :material-regular:`play_arrow`
+        :padding: 2 2 2 2
+        :link: examples/index
+        :link-type: doc
+
+        Explore examples that show how to use the different tools in practice.
+
     .. grid-item-card:: Contribute :material-regular:`group`
         :padding: 2 2 2 2
         :link: contributing
@@ -40,12 +47,14 @@ Ansys Common Tools provides a collection of tools for the PyAnsys ecosystem.
 
 
 
+
 .. toctree::
     :hidden:
     :maxdepth: 3
 
     getting_started/index
     user_guide/index
     api/index
+    examples/index
     contributing
     changelog

examples/README.txt

@@ -0,0 +1,4 @@
+Examples
+========
+
+This section shows how to use the local launcher.

examples/local_launcher/README.txt

@@ -0,0 +1,4 @@
+Examples
+========
+
+This section shows how to use the local launcher tool.

examples/local_launcher/example_httpserver_plugin/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+build-backend = "flit_core.buildapi"
+requires = [ "flit-core>=3.2,<4" ]
+
+[project]
+name = "example-httpserver-plugin"
+authors = [ { name = "ANSYS, Inc.", email = "pyansys.core@ansys.com" } ]
+classifiers = [
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+dynamic = [ "description", "version" ]
+dependencies = [ "ansys-tools-local-product-launcher", "requests" ]
+
+entry-points."ansys.tools.local_product_launcher.launcher"."example_httpserver.__fallback__" = "example_httpserver_plugin:Launcher"
+entry-points."ansys.tools.local_product_launcher.launcher"."example_httpserver.direct" = "example_httpserver_plugin:Launcher"

examples/local_launcher/example_httpserver_plugin/src/example_httpserver_plugin/__init__.py

@@ -0,0 +1,28 @@
+# Copyright (C) 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Example plugin for ansys-tools-local-product-launcher."""
+
+from .launcher import Launcher, LauncherConfig
+
+__version__ = "0.1.0"
+__all__ = ["LauncherConfig", "Launcher"]

examples/local_launcher/example_httpserver_plugin/src/example_httpserver_plugin/launcher.py

@@ -0,0 +1,104 @@
+# Copyright (C) 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Example launcher plugin, controlling an HTTP server."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import os
+import subprocess
+import sys
+
+import requests
+
+from ansys.tools.local_product_launcher.helpers.ports import find_free_ports
+from ansys.tools.local_product_launcher.interface import LauncherProtocol, ServerType
+
+
+# START_LAUNCHER_CONFIG
+@dataclass
+class LauncherConfig:
+    """Defines the configuration options for the HTTP server launcher."""
+
+    directory: str = field(default=os.getcwd())
+
+
+# END_LAUNCHER_CONFIG
+
+
+# START_LAUNCHER_CLS
+class Launcher(LauncherProtocol[LauncherConfig]):
+    """Implements launching an HTTP server."""
+
+    CONFIG_MODEL = LauncherConfig
+    SERVER_SPEC = {"main": ServerType.GENERIC}
+
+    def __init__(self, *, config: LauncherConfig):
+        """Instantiate the HTTP server launcher."""
+        self._config = config
+
+    def start(self) -> None:
+        """Start the HTTP server."""
+        port = find_free_ports()[0]
+        self._url = f"localhost:{port}"
+        self._process = subprocess.Popen(
+            [
+                sys.executable,
+                "-m",
+                "http.server",
+                "--directory",
+                self._config.directory,
+                str(port),
+            ],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            text=True,
+        )
+
+    def stop(self, *, timeout: float | None = None) -> None:
+        """Stop the HTTP server."""
+        self._process.terminate()
+        try:
+            self._process.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            self._process.kill()
+            self._process.wait()
+
+    def check(self, timeout: float | None = None) -> bool:
+        """Check if the server is running."""
+        try:
+            # As a simple check, we try to get the main page from the
+            # server. If it is accessible, we the server is running.
+            # If not, we assume it is not running.
+            requests.get(f"http://{self._url}")
+            return True
+        except requests.RequestException:
+            return False
+
+    @property
+    def urls(self) -> dict[str, str]:
+        """Addresses on which the server is serving content."""
+        return {"main": self._url}
+
+
+# END_LAUNCHER_CLS

examples/local_launcher/example_scripts/README.txt

@@ -0,0 +1,4 @@
+Examples
+========
+
+This section shows how to use the local launcher tool.

examples/local_launcher/example_scripts/cli_configure.py

@@ -0,0 +1,89 @@
+# Copyright (C) 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""
+.. _ref_cli_configure:
+
+Configure the launcher from the command line
+--------------------------------------------
+
+This example shows how to configure the ``example_httpserver`` plugin from the command line.
+It consists mostly of command-line interactions. With the exception of interactive commands,
+this example can be run when downloaded as a Jupyter notebook. The interactive commands and
+their outputs are simply shown as text.
+
+The configuration contains only a single value, ``directory``, which specifies the
+where the HTTP server is to serve files from.
+
+"""
+
+# %%
+# To see the list of launch modes for the ``example_httpserver`` product, run
+# this code:
+#
+# .. code-block:: bash
+#
+#   %%bash
+#   ansys-launcher configure example_httpserver
+#
+# Here is the output:
+#
+# ::
+#
+#   Usage: ansys-launcher configure example_httpserver [OPTIONS] COMMAND [ARGS]...
+#
+#   Options:
+#   --help  Show this message and exit.
+#
+#   Commands:
+#   direct
+
+# %%
+# Interactive configuration
+# ~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# To interactively specify the available configuration options, run
+# this command:
+#
+# .. code-block:: bash
+#
+#   ansys-launcher configure example_httpserver direct
+#
+# The preceding command might result in a session like this:
+#
+# ::
+#
+#   directory:
+#    [<current-working-directory>]: /path/to/directory
+#
+#   Updated /home/<your_username>/.config/ansys_tools_local_product_launcher/config.json
+
+# %%
+# Non-interactive configuration
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# Alternatively, you can specify the configuration fully from the command line (non-interactively):
+#
+# .. code-block:: bash
+#
+#   %%bash
+#   ansys-launcher configure example_httpserver direct --directory /path/to/directory

examples/local_launcher/example_scripts/index.rst

@@ -0,0 +1,14 @@
+Examples
+--------
+
+This section provides examples of how to use the Local Product Launcher to launch a product on
+a local machine. For these examples, the Python's built-in ``http.server`` is the application that is
+launched.
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents
+
+    cli_configure
+    py_configure
+    plugin