update migration guide

doc/source/migrations/docs-style-vale-version-update.rst

@@ -0,0 +1,48 @@
+.. _docs_style_vale_update:
+
+Doc-style action - vale update
+==============================
+
+When migrating ``ansys/actions/doc-style`` from v5 to higher versions, vale version is upgraded to ``v3``.
+Certain changes must be made to the repository to ensure that the ``doc-style`` action performs without issues.
+Additionally, it is possible to use ansys actions older than version 5 while utilizing vale version 3
+or above as input for the ``doc-style`` action like below.
+
+.. code:: yaml
+
+    doc-style:
+        name: Documentation Style Check
+        runs-on: ubuntu-latest
+        steps:
+        - name: PyAnsys documentation style checks
+            uses: ansys/actions/doc-style@v5
+            with:
+            token: ${{ secrets.GITHUB_TOKEN }}
+            vale-version: "3.4.1"
+
+In any of the above two conditions there  are two changes needs to implemented:
+
+1. Update **vocabularies** path
+
+   In order to comply with the requirements of Vale version 3 or above, it is necessary to update the vocabularies
+   path under the ``doc/styles`` directory. Specifically, the default vocabularies path should be modified from
+   ``Vocab/ANSYS`` to ``config/vocabularies/ANSYS``. This adjustment ensures that Vale can locate the required vocabulary files.
+
+   .. note:: Update ``.gitignore``
+
+    If your repository has ``.gitignore`` files under ``styles`` folder, please update them according to vocabularies changes
+
+2. Turn off **Vale Terms**
+
+   Locate the section in your ``doc/.vale.ini`` file where styles are applied.
+   Add ``Vale.Terms = NO`` under the section where styles are applied, typically marked with ``[*.{rst}]``.
+
+   .. code:: ini
+
+    [*.{rst}]
+    BasedOnStyles = Vale, Google
+    Vale.Terms = NO
+
+
+Finally, verify that the ``doc-style`` action is functioning correctly with the latest changes applied.
+Run the action and ensure that the documentation style checks are performed without any issues

doc/source/migrations/index.rst

@@ -23,10 +23,11 @@ Development version
 **Breaking changes:**
 
 - Upgrade default ``vale`` version from ``2.29.6`` to ``3.4.1`` in ``ansys/actions/doc-style`` action.
-  Vale config file ``.vale.ini`` and ``Vocab/ANSYS`` has to be changed as per `Vale section <https://dev.docs.pyansys.com/doc-style/formatting-tools.html#vale>`_ in PyAnsys developer’s guide
+- Vale config file ``.vale.ini`` and ``Vocab/ANSYS`` has to be changed.
 
 **Migration steps:**
 
+- To set up your repository to use the ``ansys/actions/doc-style`` action, see the :ref:`docs_style_vale_update`.
 - To set up your repository to use the ``ansys/actions/doc-changelog`` action, see the :ref:`docs_changelog_action_setup`.
 - To set up your repository to use the ``ansys/actions/doc-deploy-changelog`` action, see the :ref:`docs_deploy_changelog_action_setup`.
 
@@ -80,8 +81,9 @@ Version ``v4``
   for a detailed migration guide.
 
 .. toctree::
-   :hidden:
-   :maxdepth: 3
+  :hidden:
+  :maxdepth: 3
 
-   docs-changelog-setup
-   docs-deploy-changelog-setup
+  docs-style-vale-version-update
+  docs-changelog-setup
+  docs-deploy-changelog-setup