Metadata-Version: 2.4
Name: ansys-saf-templates
Version: 0.2.dev2
Summary: Collection of templates to develop in SAF solutions.
License-Expression: Apache-2.0
License-File: AUTHORS
License-File: LICENSE
Author: ANSYS, Inc.
Author-email: pyansys.core@ansys.com
Maintainer: ANSYS, Inc.
Maintainer-email: pyansys.core@ansys.com
Requires-Python: >=3.10,<4
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Other Audience
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Description-Content-Type: text/x-rst

##########################################
Solution Application Framework - Templates
##########################################

|python| |pypi| |GH-CI| |codecov| |Apache| |ruff|

.. |python| image:: https://img.shields.io/pypi/pyversions/ansys-saf-templates?logo=python&logoColor=white&label=Python
   :target: https://pypi.org/project/ansys-saf-templates/
   :alt: Python

.. |pypi| image:: https://img.shields.io/pypi/v/ansys-saf-templates.svg?logo=pypi&logoColor=white&label=PyPI
   :target: https://pypi.org/project/ansys-saf-templates/
   :alt: PyPI

.. |GH-CI| image:: https://github.com/ansys/saf-templates/actions/workflows/ci_cd_release.yml/badge.svg?label=CI
   :target: https://github.com/ansys/saf-templates/actions/workflows/ci_cd_release.yml
   :alt: GH-CI

.. |codecov| image:: https://img.shields.io/codecov/c/github/ansys/saf-templates
   :target: https://app.codecov.io/gh/ansys/saf-templates
   :alt: Codecov

.. |Apache| image:: https://img.shields.io/badge/License-Apache2.0-white.svg?labelColor=black
   :target: https://www.apache.org/licenses/
   :alt: Apache

.. |ruff| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
   :target: https://github.com/astral-sh/ruff
   :alt: Ruff


Overview
========

**SAF Templates** is a collection of Cookiecutter-based templates that help
developers quickly scaffold common components for SAF-based solution
applications. Instead of writing boilerplate code from scratch, developers can
generate ready-to-use solution steps, pages, and supporting files through the
SAF CLI, then customize them to fit their specific use case.

The package currently ships the following built-in step templates:

+---------------------------------+------------------------------------------------------+
| Template name                   | Description                                          |
+=================================+======================================================+
| ``calculator-step``             | A step that performs basic calculator operations.    |
+---------------------------------+------------------------------------------------------+
| ``hps-simple-job-step``         | A step that submits a simple job to HPS.             |
+---------------------------------+------------------------------------------------------+
| ``hps-parametric-study-step``   | A step that runs a parametric study on HPS.          |
+---------------------------------+------------------------------------------------------+
| ``instance-mgmt-geometry-step`` | A step for basic Geometry instance management.       |
+---------------------------------+------------------------------------------------------+

Beyond the built-in templates, SAF Templates supports a **plugin architecture**
that allows developers and teams to create, package, and share their own
template repositories. This means you can build reusable templates tailored to
your organization's patterns and distribute them across projects or to the
wider community.

Contributions are welcomed. If you have a useful template that could benefit
other SAF developers, consider contributing it back to the project or
publishing your own template plugin repository.


Installation
============

SAF Templates comes bundled with SAF CLI since SAF CLI version 3.7. However, **it is
mandatory to have SAF CLI version 4.0 or later installed to use the templates**.
Using previous versions of SAF CLI might produce unexpected results or even errors
when attempting to add a step. This documentation assumes that SAF CLI version 4.0 or
later is installed.

Use the following command if you want to manually install a newer version of the SAF
Templates package. Make sure to install it in the python environment where SAF CLI is
installed:

.. code-block:: bash

    pip install ansys-saf-templates


Quick start
===========

You can list the available templates by running:

.. code-block:: bash

    saf templates

This will show all the templates available in ansys-saf-templates as well as any
additional templates from installed plugins.

Add a new step to your solution using the SAF CLI command:

.. code-block:: bash

    saf add-step <my_solution>

The CLI will interactively guide you through selecting a template and providing
the required parameters. Otherwise, you can directly pass all the necessary
information as command-line arguments:

.. code-block:: bash

    saf add-step <my_solution> --step-name <step_name> --ui-framework <ui_framework> --template <template_name>


Documentation
=============

The `official documentation`_ contains:

- `Overview`_ — What SAF Templates is and its key features.
- `User guide`_ — Installation, prerequisites, and usage instructions.
- `Template gallery`_ — Browse all available templates.
- `Contribute`_ — How to add your own templates.


Troubleshooting
===============

For troubleshooting or reporting issues, open an issue in the
`project repository <https://github.com/ansys/saf-templates/issues>`_.

Follow these steps to report an issue:

- Go to the project repository.
- Click on the ``Issues`` tab.
- Click on the ``New Issue`` button.
- Provide a clear and detailed description of the issue you are facing.
- Include any relevant error messages, code snippets, or screenshots.

Additionally, you can refer to the `official documentation`_ for additional
resources and troubleshooting guides.


License
=======

This project is licensed under the Apache 2.0 License. See the `LICENSE`_ file
for details.


.. _official documentation: https://saf-templates.docs.solutions.ansys.com
.. _Overview: https://saf-templates.docs.solutions.ansys.com/version/stable/overview/index.html
.. _User guide: https://saf-templates.docs.solutions.ansys.com/version/stable/user_guide/index.html
.. _Template gallery: https://saf-templates.docs.solutions.ansys.com/version/stable/template_gallery/index.html
.. _Contribute: https://saf-templates.docs.solutions.ansys.com/version/stable/contribute/index.html
.. _LICENSE: https://github.com/ansys/saf-templates/blob/main/LICENSE


