Metadata-Version: 2.4
Name: ansys-saf-templates
Version: 0.2.dev0
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                        | 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
============

Ensure you have all the necessary `prerequisites`_. Then, refer to the
`installation guidelines`_ for detailed instructions on how to install the
project in your system.


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

The `official documentation`_ of SAF Templates contains
the following chapters:

- `Getting started`_. This section provides a brief overview and instructions on
  how to get started with the project. It typically includes information on how
  to install the project, set up any necessary dependencies, and run a basic
  example or test to ensure everything is functioning correctly.

- `User guide`_. The user guide section offers detailed documentation and
  instructions on how to use the project. It provides comprehensive explanations
  of the project's features, functionalities, and configuration options. The
  user guide aims to help users understand the project's concepts, best
  practices, and recommended workflows.

- `Contribute`_. This section provides guidelines and instructions on how to
  contribute to the project. It includes information on how to set up the
  development environment, run tests, submit pull requests, and follow
  contribution guidelines.


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

For troubleshooting or reporting issues, open an issue in the project
repository.

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.


Changelog
=========

The changelog section provides a summary of notable changes for each version of
SAF Product Configuration for Python. It helps you keep track of updates, bug
fixes, new features, and improvements made to the project over time.

To view the complete changelog, visit the project repository and navigate
to the `CHANGELOG`_ file. It provides a comprehensive list of changes
categorized by version, along with brief descriptions of each change.


How it works?
=============

Adding templates to the repository
----------------------------------

**Note:** currently only step templates can be added to the repository. Support for other types of templates (e.g., solution templates) is going to be added in the future.

To add a new step template, create a new directory under ``src/ansys/saf/templates/steps`` and add the template files to that directory.
The template files should adhere to the following structure:

.. code-block:: text

    my_step/
    |
    ├── {{cookiecutter.__solution_module_name}}/
    |   |
    |   ├── solution/
    |   |   |
    |   |   └── {{cookiecutter.__step_module_name}}.py  # definition of StepModel subclass
    |   |
    |   └── ui/pages/
    |       |
    |       └── {{cookiecutter.__ui_page_file_name}}.py  # definition of the step's UI
    |
    ├── hooks
    |   |
    |   ├── pre_gen_project.py  # Not required, only if pre-generation hooks are needed
    |   |
    |   └── post_gen_project.py
    |
    └── cookiecutter.json

An entry for the new template has to be added to ``templates.toml``.

.. code-block:: toml

    [templates.my-step]
    location = "steps/my_step"
    type = "step"
    description = "a step that performs some action"

    [templates.my-step.dependencies]
    pendulum = ">=3.2.0"

This example assumes that the template was added under ``src/ansys/saf/templates/steps/my_step``. This is not a requirement as the step templates can be added anywhere under
``src/ansys/saf/templates/steps``. The only requirement is that the ``location`` field in the ``templates.toml`` entry must be a relative path under ``src/ansys/saf/templates``
that points to the template's root.

The template name is defined inside the square brackets (``[templates.<template-name>]``) and must be unique across all templates in the repository, as it is used to
identify the template to be generated from SAF CLI. Kebab-case should be used for template names.

The ``type`` field indicates the type of the template, which currently can only be ``step``.

The ``description`` field provides a brief description of the template that is going to be displayed in SAF CLI when listing the available templates.

Any new dependencies required by the template should be added to the ``dependencies`` section of the template entry in a format that is valid for the pyproject.toml.
These dependencies are going to be automatically installed in the generated project's virtual environment when the template is generated.

All fields are mandatory except for ``dependencies``. Any template that is not included in the ``templates.toml`` file won't be discoverable.

Creating a new template plugin repository
-----------------------------------------

To create a repository that can be used as a template plugin it needs:

1. to adhere to a certain structure
2. to be declared as a plugin in its ``pyproject.toml``,
3. to have a ``__init__.py`` file that includes a function returning the path to the plugin, and
4. to include the configuration of the defined templates in a ``templates.toml`` file.

Structure of a template plugin repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The structure of a template plugin repository should be as follows:

.. code-block:: text

    my_template_plugin/
    |
    ├── pyproject.toml  # includes the declaration of the plugin entry-point
    |
    └── src/package/templates_module
        |
        ├── __init__.py  # includes the get_plugin_path function
        |
        ├── templates.toml  # includes the configuration of the templates defined in this plugin
        |
        └── <template_structure>  # one or more directories containing the templates defined in this plugin

Declare an entry-point in pyproject.toml
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The template plugin repository needs to declare itself as a plugin in its ``pyproject.toml``. The entry-point group ``"ansys_saf_templates"`` is mandatory.
The important part of the entry-point is its value ``"package.templates_module:get_plugin_path"``. Its name ``plugin_path`` is not relevant and can be
modified.

.. code-block:: toml

    [project.entry-points."ansys_saf_templates"]
    plugin_path = "package.templates_module:get_plugin_path"

The first part of the entry-point value must match the installation path of the repository, so the ``pyproject.toml`` should also include:

.. code-block:: toml

    [[tool.poetry.packages]]
    include = "package/templates_module"
    from = "src"

The second part points to the function ``get_plugin_path`` that we must define in the ``__init__.py`` file.

Add the function ``get_plugin_path`` to ``__init__.py``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The content of the ``__init__.py`` should be:

.. code-block:: python

    from pathlib import Path


    def get_plugin_path() -> Path:
        """Return the path to the cookiecutter template."""
        return Path(__file__).parent.resolve()

Add the template's configuration file ``templates.toml``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The configuration of all the templates is defined in a single ``templates.toml`` file under ``src/package/templates_module``. This file must contain an entry for every
template containing the fields described in the previous section.


.. _prerequisites: https://saf-templates.docs.solutions.ansys.com/version/stable/getting-started#prerequisites
.. _installation guidelines: https://saf-templates.docs.solutions.ansys.com/version/stable/getting-started#installation
.. _official documentation: https://saf-templates.docs.solutions.ansys.com
.. _Getting started: https://saf-templates.docs.solutions.ansys.com/version/stable/getting-started.html
.. _User guide: https://saf-templates.docs.solutions.ansys.com/version/stable/user-guide.html
.. _API reference: https://saf-templates.docs.solutions.ansys.com/version/stable/api/index.html
.. _Examples: https://saf-templates.docs.solutions.ansys.com/version/dev/examples.html
.. _Contribute: https://saf-templates.docs.solutions.ansys.com/version/stable/contribute.html
.. _LICENSE: https://github.com/ansys/saf-templates/blob/main/LICENSE
.. _CHANGELOG: https://github.com/ansys/saf-templates/blob/main/CHANGELOG.md


