##############################################
Ansys Solutions {{cookiecutter.solution_name}}
##############################################

.. note::
  This content needs to be configured according to the project specifics.


Introduction
============

.. note::
  Add here a description of the project.

Ansys Solutions {{cookiecutter.solution_name}}

  * Project name: **{{ cookiecutter.__project_name_slug }}**
  * Solution name: **{{ cookiecutter.__solution_name_slug }}**
  * Package name: **{{ cookiecutter.__pkg_name }}**


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

Prerequisites
-------------

Python version support
~~~~~~~~~~~~~~~~~~~~~~

.. note::
  Add here the supported Python versions.

For example:

  Officially Python 3.8 to 3.10

Private PyPI servers
~~~~~~~~~~~~~~~~~~~~

Connection to Ansys-Solutions private PyPI server is required. Access is controlled via a ``Personal Access Token (PAT)`` which is available
in the `Solutions Developer's Guide <https://dev-docs.solutions.ansys.com/index.html>`_. To declare the PAT on your system:

  1. Visit the `Connecting to the private PyPI <https://dev-docs.solutions.ansys.com/getting_started/canonical_development_environment.html#connecting-to-the-private-pypi-servers>`_ section of the `Solutions Developer's Guide <https://dev-docs.solutions.ansys.com/index.html>`_,
     navigate to the Private PyPI servers section and copy the token related to Ansys-Solutions PyPI.

  2. Create a system environment variable named SOLUTIONS_PRIVATE_PYPI_PAT and assign the token.

.. note::
  In addition to the Ansys-Solutions private PyPI server, you can add several private sources such as PyAnsys private PyPI server.

Flagship products
~~~~~~~~~~~~~~~~~

.. note::
  Add here the name and the versions of Ansys flagship products needed to run the solution.
  Remove this section if useless.

For example:

  .. list-table:: Required flagship products
    :widths: 200 100
    :header-rows: 1

    * - Product
      - Versions

    * - SpaceClaim
      - R22.2 to latest

    * - Fluent
      - R23.1 to latest

    * - XXX
      - RXX.X

Setup the development environment
---------------------------------

In order to start using the solution or to develop inside the solution you need to install the Python ecosystem required.

``poetry`` is the dependency manager tool used in this project. The dependencies are declared in ``pyproject.toml`` at project root.

From now on, the version of the dependency manager tool must be defined in the pyproject.toml file.

For example, if you are using Poetry version 1.4.2 (the latest poetry version), the following lines must be part of your pyproject.toml file, after the ``build-system`` section:

  .. code:: bash

    [build-system-requirements]
    build-system-version = "1.4.2"

For this project, the poetry version used is 1.4.2.

Otherwise if you want to use the version of poetry of your choice, you can use the -s option to run the setup_environment.py script.
For example, ``python setup_environment.py -d all -s 1.3``

Last but not least, please make sure that the version of poetry in your pyproject.toml file is the same as in the ci.yml file (located in the .github\workflows folder) for consistency.

Automatic installation
~~~~~~~~~~~~~~~~~~~~~~

The automatic installation consists in running the setup_environment.py script at project root. Basically, this script creates a virtual environment,
and installs the dependency management tool ``poetry``. The ``-d`` option is used to specify the group of dependencies to install. For production
dependencies use ``-d run``, for doc dependencies use ``-d doc``, for tests dependencies ``-d tests``, and for build dependencies use ``-d build``.

To install the complete development environment follow these instructions:

1. Navigate to project root:

  .. code:: bash

    cd {{ cookiecutter.__project_name_slug }}

2. Install ``toml`` and ``packaging``:

  .. code:: bash

    pip install toml packaging

3. Setup the Python environment (the ``-d all`` option means that ``run``, ``doc``, ``tests``, and ``build`` dependencies will be installed):

  .. code:: bash

    python setup_environment.py -d all

4. Activate the virtual environment:

  * For Linux system:

    .. code:: bash

      source .venv/bin/activate

  * For Windows CMD:

    .. code:: bash

      .venv\Scripts\activate.bat

  * For Windows Powershell:

    .. code:: bash

      .venv\Scripts\Activate.ps1

From now on, all the commands listed in the documentation must be executed within the virtual environment.

Update dependencies
~~~~~~~~~~~~~~~~~~~

To add a new dependency or to update the version of an existing dependency use the ``poetry add`` command.

For packages collected from public PyPI run:

  .. code:: bash

    poetry add <name-of-package>

For packages collected from Solutions private PyPI run:

  .. code:: bash

    poetry add <name-of-package> --source solutions-private-pypi

For packages collected from PyAnsys private PyPI run:

  .. code:: bash

    poetry add <name-of-package> --source pyansys-private-pypi

To request a specific version of a package add ``==<version>``:

  .. code:: bash

    poetry add <name-of-package>==<version>

Start the application
=====================

To start the application run the following command anywhere in the project:

  .. code:: bash

    saf run


Code style check
================

In this project, the following code style checks are required:

  * black

  * isort

  * flake8

  * codespell

  * pydocstyle

All-in-one checks using pre-commit
----------------------------------

All those checks can be triggered with one single tool: ``pre-commit``. ``pre-commit`` is a GIT hook allowing to trigger all the code style commands at once at the point when you perform a git commit.
``pre-commit`` prevents you from forgetting to run the required actions against your code and it ensures the exact same style policies are applied. The code style policy is defined in the
``.pre-commit-config.yaml`` at project root.

Developers are not forced but encouraged to install ``pre-commit`` via:

  .. code:: bash

    python -m pip install pre-commit

  .. code:: bash

    pre-commit install

To run pre-commit:

  .. code:: bash

    pre-commit run --all-files --show-diff-on-failure

How to remove ``pre-commit``?

  * Navigate to the git directory at the root of the repository

  * Select the hooks directory

  * Remove pre-commit file

Sequential checks
-----------------

Install code style requirements:

  .. code:: bash

    python -m pip install -r requirements/requirements_style.txt

Run black:

  .. code:: bash

    python -m black .

Run isort:

  .. code:: bash

    python -m isort .

Run flake8:

  .. code:: bash

    python -m flake8 .

Run codespell:

  .. code:: bash

    python -m codespell .


Testing

**Unit tests** and **Integration tests** are executed via the ``pytest`` framework.

To run the unit tests:

  .. code:: bash

    pytest tests/unit

To run the integration tests:

  .. code:: bash

    pytest tests/integration

To run all the tests:

  .. code:: bash

    pytest

To compute the coverage ratio and to generate a report:

  .. code:: bash

    pytest -p no:faulthandler --cov=ansys.solutions --cov-report=term --cov-report=xml --cov-report=html -vvv

To run the tests against multiple Python versions automatically:

  .. code:: bash

    tox -e py


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

Run the following command:

  .. code:: bash

    sphinx-build doc/source doc/build/html --color -vW -bhtml

Build
=====

Using the build module
----------------------

Build the package:

  .. code:: bash

    python -m build

Using poetry
------------

Build the package:

  .. code:: bash

    poetry build

Automation using TOX
====================

``tox`` is a tool for automating all the commands listed above from code styling to testing and build. ``tox`` creates its own virtual environment so anything
being tested is isolated from the project in order to guarantee project's integrity. The following environments commands are provided:

  * **tox -e style**: will check for coding style quality.

  * **tox -e py**: checks for unit tests.

  * **tox -e py-coverage**: checks for unit testing and code coverage.

  * **tox -e doc**: checks for documentation building process.

  * **tox -e build**: checks source code build.
