add a section to convert the app to an executable to examples (#2100)

* add a section to convert the app to an executable * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * fix vocabulary mistakes * add "datas" to the accepted list of word for codespell * Apply suggestions from code review Co-authored-by: German <[email protected]> * add details * fix vale * Apply suggestions from code review Co-authored-by: Kathy Pippert <[email protected]> * Apply suggestions from code review Co-authored-by: Kathy Pippert <[email protected]> * put the links in links.rst --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Camille <[email protected]> Co-authored-by: German <[email protected]> Co-authored-by: Kathy Pippert <[email protected]> Co-authored-by: German <[email protected]>
ansys · Jun 16, 2023 · b38593e · b38593e
1 parent c03293f
commit b38593e
Show file tree

Hide file tree

Showing 4 changed files with 114 additions and 6 deletions.
diff --git a/doc/source/examples/extended_examples/executable/cli_rotor.spec b/doc/source/examples/extended_examples/executable/cli_rotor.spec
@@ -0,0 +1,59 @@
+# -*- mode: python ; coding: utf-8 -*-
+
+import os
+import importlib
+
+root = os.path.dirname(importlib.import_module("ansys.api.mapdl").__file__)
+# The ``files_to_add`` list contains tuples that define the mapping between the original file paths and their corresponding paths within the executable folder.
+# Note: If you have chosen the ``onefile`` mode, the files in ``files_to_add`` are integrated into the executable file.
+files_to_add = [
+    (os.path.join(root, "VERSION"), os.path.join(".", "ansys", "api", "mapdl"))
+]
+
+block_cipher = None
+
+
+a = Analysis(
+    ['cli_rotor.py'],
+    pathex=[],
+    binaries=[],
+    datas=files_to_add,
+    hiddenimports=[],
+    hookspath=[],
+    hooksconfig={},
+    runtime_hooks=[],
+    excludes=[],
+    win_no_prefer_redirects=False,
+    win_private_assemblies=False,
+    cipher=block_cipher,
+    noarchive=False,
+)
+pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)
+
+exe = EXE(
+    pyz,
+    a.scripts,
+    [],
+    exclude_binaries=True,
+    name='cli_rotor',
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=True,
+    console=True,
+    disable_windowed_traceback=False,
+    argv_emulation=False,
+    target_arch=None,
+    codesign_identity=None,
+    entitlements_file=None,
+)
+coll = COLLECT(
+    exe,
+    a.binaries,
+    a.zipfiles,
+    a.datas,
+    strip=False,
+    upx=True,
+    upx_exclude=[],
+    name='cli_rotor',
+)
diff --git a/doc/source/examples/extended_examples/executable/executable.rst b/doc/source/examples/extended_examples/executable/executable.rst
@@ -39,7 +39,7 @@ is used. Another suitable package is the builtin package
 
 First, you must convert the script to a function. You can
 accomplish this by using the input arguments
-in a function signature. 
+in a function signature.
 
 In this case, the following arguments must be specified:
 
@@ -101,6 +101,50 @@ This code shows how you can input other arguments:
    The first natural frequency is 344.28 Hz.
 
 
+Convert the app to an executable file
+=====================================
+
+Using the Python library `PyInstaller <pyinstaller_>`_, you can convert the app to an executable file.
+However, for the app to work, you must add the ``VERSION`` file that specifies the PyMAPDL version to the executable file.
+
+Start by generating the `specification file <pyinstaller_spec_files_>`_ for the app.
+At the root of the project, execute the following command:
+
+
+.. code:: console
+
+   pyi-makespec cli_rotor.py
+
+PyInstaller provides two modes for generating executables:
+
+- ``onedir`` (default): This mode generates a folder that includes the executable file along with its dependencies.
+- ``onefile``: This mode has PyInstaller generate a single executable file.
+
+To generate the executable file in ``onefile`` mode, include the argument ``--onefile`` in the command:
+
+.. code:: console
+
+   pyi-makespec cli_rotor.py --onefile
+
+Then, add the link to the ``VERSION`` file from the PyMAPDL package in the ``cli_rotor.spec`` file:
+
+
+.. literalinclude:: cli_rotor.spec
+   :language: python
+   :lines: 1-30
+   :emphasize-lines: 3-11,20
+
+
+Generate the executable file from the ``cli_rotor.spec`` file:
+
+.. code:: console
+
+   pyinstaller cli_rotor.spec
+
+
+The output is an executable file named ``cli_rotor.exe`` in the directory ``./dist/cli_rotor``.
+
+
 Advanced usage
 ==============
 
@@ -138,7 +182,7 @@ Here are descriptions for values used in the preceding code:
 
 - ``-gravity``: Location of the watermark in case the watermark is
   smaller than the image.
-- ``COMPOSITE``: Path to the ImageMagick ``composite`` function. 
+- ``COMPOSITE``: Path to the ImageMagick ``composite`` function.
 - ``watermark.png``: Name of the PNG file with the watermark image.
 - ``volumes_with_watermark.jpg``: Name of the JPG file to save the output to.
 
@@ -159,7 +203,7 @@ For example, you can execute the previous example on a GitHub runner
 using this approach (non-tested):
 
 .. code:: yaml
-  
+
    my_job:
       name: 'Generate watermarked images'
       runs-on: ubuntu-latest
@@ -174,7 +218,7 @@ using this approach (non-tested):
          - name: "Install ansys-mapdl-core"
            run: |
                python -m pip install ansys-mapdl-core
-         
+
          - name: "Install ImageMagic"
            run: |
             sudo apt install imagemagick

diff --git a/doc/source/links.rst b/doc/source/links.rst
@@ -92,10 +92,12 @@
 .. _What_is_the_Windows_Subsystem_for_Linux: https://docs.microsoft.com/en-us/windows/wsl/about
 .. _open_port_windows_10: https://answers.microsoft.com/en-us/windows/forum/all/how-to-open-port-in-windows-10-firewall/f38f67c8-23e8-459d-9552-c1b94cca579a/
 .. _disabling_firewall_on_wsl: https://github.com/cascadium/wsl-windows-toolbar-launcher#firewall-rules
-.. _article_good_unit_test: https://stackoverflow.com/questions/61400/what-makes-a-good-unit-test 
+.. _article_good_unit_test: https://stackoverflow.com/questions/61400/what-makes-a-good-unit-test
 .. _vscode_attach_to_container: https://code.visualstudio.com/docs/devcontainers/attach-container
 .. _ubuntu_firewall: https://ubuntu.com/server/docs/security-firewall
 .. _pyvista_eye_dome_lighting: https://docs.pyvista.org/examples/02-plot/edl.html
+.. _pyinstaller: https://pyinstaller.org
+.. _pyinstaller_spec_files: https://pyinstaller.org/en/stable/spec-files.html
 
 .. #Github links:
 .. _gh_creating_pat: https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token

diff --git a/doc/styles/Vocab/ANSYS/accept.txt b/doc/styles/Vocab/ANSYS/accept.txt
@@ -37,6 +37,7 @@ CentOS
 CentOS7
 Chao
 container_layout
+datas
 delet
 docker
 Docker
@@ -63,6 +64,7 @@ hostname
 Imagemagick
 ImageMagick
 imagin
+importlib
 Intro to Ansys Mechanical APDL Scripting
 ist
 Julia
@@ -87,6 +89,7 @@ Newton-Raphson
 nin
 nonlinearities
 NumPy
+onefile
 optiSLang
 parm
 performant
@@ -143,4 +146,4 @@ Windows Subsystem
 Windows Subsystem for Linux
 wsl
 WSL
-Zhu
+Zhu