Doc: Add tutorials related to deployment

Including in the documentation a section related to deployment,
and also tutorials associated to the following tools:
PyInstaller, cx_Freeze, and fbs.

Task-number: PYSIDE-901
Change-Id: I6162b039b5df3eced38ce65fe7cb143be9f0de82
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>

5 files changed, 431 insertions, 0 deletions

diff --git a/sources/pyside2/doc/contents.rst b/sources/pyside2/doc/contents.rst
index 645f461e5..464f6e1da 100644
--- a/sources/pyside2/doc/contents.rst
+++ b/sources/pyside2/doc/contents.rst
@@ -8,6 +8,7 @@
     faq.rst
     gettingstarted.rst
     tutorials/index.rst
+    deployment.rst
     pysideapi2.rst
     pysideversion.rst
     licenses.rst
diff --git a/sources/pyside2/doc/deployment-cxfreeze.rst b/sources/pyside2/doc/deployment-cxfreeze.rst
new file mode 100644
index 000000000..40b65621b
--- /dev/null
+++ b/sources/pyside2/doc/deployment-cxfreeze.rst
@@ -0,0 +1,130 @@
+=====================
+|project| & cx_Freeze
+=====================
+
+`cx_Freeze <https://anthony-tuininga.github.io/cx_Freeze/>`_ allows you to freeze your Python
+application into executables.
+The supported platforms are Linux, macOS, Windows, FreeBSD, among others.
+
+
+You can read the `official documentation <https://cx-freeze.readthedocs.io/en/latest/index.html>`_
+to clarify any further question, and remember to contribute to
+the project by `filing issues <https://sourceforge.net/projects/cx-freeze/>`_
+if you find any, or contributing to `their development <https://bitbucket.org/anthony_tuininga/cx_freeze/src>`_.
+
+Preparation
+===========
+
+Installing `cx_Freeze` can be done via **pip**::
+
+    pip install cx_freeze
+
+If you are using a virtual environment, remember to activate it before
+installing `cx_Freeze` into it.
+
+After the installation, you will have the `cxfreeze` binary to deploy
+your application.
+
+Freezing an application
+=======================
+
+There are three options to work with `cx_Freeze`:
+
+ 1. Using the `cxfreeze` script.
+ 2. Creating `setup.py` script to build the project.
+ 3. Using the module classes directly (for advanced purposes).
+
+We will cover the first two uses cases.
+
+Creating an example
+-------------------
+
+Now, consider the following simple script, named `hello.py`::
+
+    import sys
+    import random
+    from PySide2.QtWidgets import (QApplication, QLabel, QPushButton,
+                                   QVBoxLayout, QWidget)
+    from PySide2.QtCore import Slot, Qt
+
+    class MyWidget(QWidget):
+        def __init__(self):
+            QWidget.__init__(self)
+
+            self.hello = ["Hallo Welt", "你好，世界", "Hei maailma",
+                "Hola Mundo", "Привет мир"]
+
+            self.button = QPushButton("Click me!")
+            self.text = QLabel("Hello World")
+            self.text.setAlignment(Qt.AlignCenter)
+
+            self.layout = QVBoxLayout()
+            self.layout.addWidget(self.text)
+            self.layout.addWidget(self.button)
+            self.setLayout(self.layout)
+
+            # Connecting the signal
+            self.button.clicked.connect(self.magic)
+
+        @Slot()
+        def magic(self):
+            self.text.setText(random.choice(self.hello))
+
+    if __name__ == "__main__":
+        app = QApplication(sys.argv)
+
+        widget = MyWidget()
+        widget.resize(800, 600)
+        widget.show()
+
+        sys.exit(app.exec_())
+
+
+Using `cxfreeze` executable
+---------------------------
+
+The command line to proceed will look like this::
+
+    cxfreeze hello.py
+
+This command will create a `dist/` directory that will contain the
+executable and a `lib/` directory including all the shared libraries.
+
+To launch the application, you need to just go to the `dist/` directory
+and execute the file::
+
+    cd dist/
+    ./main
+
+
+Using a setuptools script
+-------------------------
+
+For this process, you will need an additional script called `setup.py`::
+
+    import sys
+    from cx_Freeze import setup, Executable
+
+    setup(name = "MyApp",
+          version = "0.1",
+          description = "My GUI App",
+          executables = [Executable("hello.py")])
+
+After that, you need to build the project using it::
+
+    python setup.py build
+
+This step will create a `build/` directory with the following structure::
+
+    build
+    └── exe.linux-x86_64-3.7
+        └── lib
+        └── main
+
+The first directory inside `build/` will depend on the platform
+you are using, in this case a `x86_64` Linux using Python 3.7.
+The structure is the same as previously described, and you can simply
+enter the directory and execute the file::
+
+    cd build/exe.linux-x86_64-3.7
+    ./main
diff --git a/sources/pyside2/doc/deployment-fbs.rst b/sources/pyside2/doc/deployment-fbs.rst
new file mode 100644
index 000000000..94c52a08b
--- /dev/null
+++ b/sources/pyside2/doc/deployment-fbs.rst
@@ -0,0 +1,106 @@
+===============
+|project| & fbs
+===============
+
+`fbs <https://build-system.fman.io>`_ provides a powerful environment for packaging,
+creating installers, and signing your application, but also for managing the application's updates.
+Since it is based on PyInstaller, it currently supports Linux, macOS, and Windows.
+
+You can read the `official tutorial <https://github.com/mherrmann/fbs-tutorial>`_ for more
+details on how to use `fbs`, or check the
+`documentation <https://build-system.fman.io/manual/>`_ for a complete set of features and
+options.
+
+Preparation
+===========
+
+Installing `fbs` can be done via **pip**::
+
+    pip install fbs pyinstaller==3.4
+
+If you are using a virtual environment, remember to activate it before
+installing it.
+
+After the installation, you will be able to use the `fbs` executable.
+
+Starting a new project
+======================
+
+`fbs` provides nice features that allow you to create a base
+project structure by executing the following command::
+
+    fbs startproject
+
+This process will prompt you to answer many questions to configure the details
+of your project, like:
+
+ * Application name
+ * Author name
+ * Qt bindings (PySide2 or PyQt5)
+ * Bundle indentified (for macOS)
+
+After the process finishes, you will have a `src/` directory that
+will contain the following structure::
+
+    └── src
+        ├── build
+        │   └── settings
+        └── main
+            ├── icons
+            │   ├── base
+            │   ├── linux
+            │   └── mac
+            └── python
+
+Inside the `settings` directory you can find a couple of `json` files
+that you can edit to include more information about your project.
+
+The main file will be under the `python` directory, and its content by default is::
+
+    from fbs_runtime.application_context import ApplicationContext
+    from PySide2.QtWidgets import QMainWindow
+
+    import sys
+
+    class AppContext(ApplicationContext):           # 1. Subclass ApplicationContext
+        def run(self):                              # 2. Implement run()
+            window = QMainWindow()
+            version = self.build_settings['version']
+            window.setWindowTitle("MyApp v" + version)
+            window.resize(250, 150)
+            window.show()
+            return self.app.exec_()                 # 3. End run() with this line
+
+    if __name__ == '__main__':
+        appctxt = AppContext()                      # 4. Instantiate the subclass
+        exit_code = appctxt.run()                   # 5. Invoke run()
+        sys.exit(exit_code)
+
+The example will show an empty `QMainWindow`, and you can execute it by running::
+
+    fbs run
+
+Freezing the application
+========================
+
+Once you verify that the application is properly working,
+you can continue with the freezing process::
+
+    fbs freeze
+
+After the process finishes, you will get a message stating the location
+of your executable, e.g.::
+
+    Done. You can now run `target/MyApp/MyApp`. If that doesn't work, see
+    https://build-system.fman.io/troubleshooting.
+
+
+Then executing the application will result in the same window
+you saw with the `fbs run` command::
+
+    cd target/MyApp/
+    ./MyApp
+
+.. note:: This is the case for Linux. For other platforms like macOS, you will need to
+          enter the directory: `target/MyApp.app/Contents/MacOS`, and for
+          Windows you will find a `MyApp.exe` executable.
diff --git a/sources/pyside2/doc/deployment-pyinstaller.rst b/sources/pyside2/doc/deployment-pyinstaller.rst
new file mode 100644
index 000000000..8e6a76052
--- /dev/null
+++ b/sources/pyside2/doc/deployment-pyinstaller.rst
@@ -0,0 +1,124 @@
+=======================
+|project| & PyInstaller
+=======================
+
+`PyInstaller <https://www.pyinstaller.org/>`_ allows you to freeze your python
+application into a stand-alone executable.
+The supported platforms are Linux, macOS, Windows, FreeBSD, and others.
+
+One of the main goals of `PyInstaller` is to be compatible with 3rd-party
+Python modules, e.g.: |pymodname|.
+
+You can read the `official documentation <https://www.pyinstaller.org/documentation.html>`_
+to clarify any further question, and remember to contribute to
+`the project <https://github.com/pyinstaller/pyinstaller>`_
+by filing issues if you find any, or contributing to their development.
+
+Preparation
+===========
+
+Installing `PyInstaller` can be done via **pip**::
+
+    pip install pyinstaller
+
+If you are using a virtual environment, remember to activate it before
+installing `PyInstaller` into it.
+
+After the installation, the `pyinstaller` binary will be located in the `bin/`
+directory of your virtual environment, or where your Python executable is located.
+
+If that directory is not in your `PATH`, you need to include the whole path
+when executing `pyinstaller`.
+
+.. warning:: If you already have PySide2 or Shiboken2 installed in your system, PyInstaller will pick them
+             instead of your virtual environment ones.
+
+Freezing an application
+=======================
+
+`PyInstaller` has many options that you can use.
+To learn more about them you can just run `pyinstaller -h`.
+
+Two main features are the option to package the whole project
+(including the shared libraries) into one executable file (`--onefile`),
+and to prepare a directory that will contain
+an executable next to all the used libraries.
+
+Additionally, for Windows you can enable opening a console during the
+execution with the option `-c` (or equivalent `--console` or `--nowindowed`).
+Further, you can specify to not open such console window
+on macOS and Windows with the option `-w` (or equivalent `--windowed` or `--noconsole`).
+
+Creating an example
+-------------------
+
+Now, consider the following simple script, named `hello.py`::
+
+    import sys
+    import random
+    from PySide2.QtWidgets import (QApplication, QLabel, QPushButton,
+                                   QVBoxLayout, QWidget)
+    from PySide2.QtCore import Slot, Qt
+
+    class MyWidget(QWidget):
+        def __init__(self):
+            QWidget.__init__(self)
+
+            self.hello = ["Hallo Welt", "你好，世界", "Hei maailma",
+                "Hola Mundo", "Привет мир"]
+
+            self.button = QPushButton("Click me!")
+            self.text = QLabel("Hello World")
+            self.text.setAlignment(Qt.AlignCenter)
+
+            self.layout = QVBoxLayout()
+            self.layout.addWidget(self.text)
+            self.layout.addWidget(self.button)
+            self.setLayout(self.layout)
+
+            # Connecting the signal
+            self.button.clicked.connect(self.magic)
+
+        @Slot()
+        def magic(self):
+            self.text.setText(random.choice(self.hello))
+
+    if __name__ == "__main__":
+        app = QApplication(sys.argv)
+
+        widget = MyWidget()
+        widget.resize(800, 600)
+        widget.show()
+
+        sys.exit(app.exec_())
+
+
+Since it has a UI, we will use the `--windowed` option.
+
+The command line to proceed will look like this::
+
+    pyinstaller --name="MyApplication" --windowed hello.py
+
+This process will create a `dist/` and `build/` directory.
+The executable and all the shared libraries required by your application
+will be placed inside `dist/MyApplication`.
+
+To execute the frozen application you can go inside `dist/MyApplication` and
+execute the program::
+
+    cd dist/MyApplication/
+    ./MyApplication
+
+.. note:: The directory inside `dist/` and the executable will have the same name.
+
+If you prefer to have everything bundled into one executable, i.e.:
+no shared libraries next to the executable, you can use the option
+`--onefile`::
+
+    pyinstaller --name="MyApplication" --windowed --onefile hello.py
+
+This process will take a bit longer, but in the end you will discover
+an executable inside the `dist/` directory that you can execute::
+
+    cd dist/
+    ./MyApplication
diff --git a/sources/pyside2/doc/deployment.rst b/sources/pyside2/doc/deployment.rst
new file mode 100644
index 000000000..582e38992
--- /dev/null
+++ b/sources/pyside2/doc/deployment.rst
@@ -0,0 +1,70 @@
+==========
+Deployment
+==========
+
+Deploying or freezing an application is a crucial part of many Python projects.
+Most large projects are not based on a single Python file, so
+the distribution of these applications becomes more difficult.
+
+The options for a project are:
+ 1. Sending a normal zip-file with the application's content.
+ 2. Building a proper `Python package (wheel) <https://packaging.python.org/>`_.
+ 3. Freezing the application in a single binary file, or into a directory.
+
+For the **third** option, there are many available tools:
+ * `PyInstaller <https://www.pyinstaller.org/>`_,
+ * `cx_Freeze <https://anthony-tuininga.github.io/cx_Freeze/>`_,
+ * `py2exe <http://www.py2exe.org/>`_,
+ * `py2app <https://py2app.readthedocs.io/en/latest/>`_,
+
+Since |project| is a cross-platform framework,
+we would like to focus on solutions that at least work on
+the three major platform supported by Qt: Linux, macOS, and Windows.
+
+The following table summarizes the above mentioned tools support:
+
+===========   =======   =====   =====   =======
+Name          License   Linux   macOS   Windows
+===========   =======   =====   =====   =======
+py2exe        MIT       no      no      yes
+py2app        MIT       no      yes     no
+cx_Freeze     MIT       yes     yes     yes
+PyInstaller   GPL       yes     yes     yes
+===========   =======   =====   =====   =======
+
+From the table we can see that only *cx_Freeze* and *PyInstaller*
+meet our requirements.
+
+All tools are command-line based, and it could become
+a hard task to include more resources to your application, such as
+images, icons, and meta-information, because you will need to create
+special hooks or separate scripts to handle them.
+Additionally, since this only
+allows you to freeze your current application, you don't have
+any mechanism to update your application.
+
+To cover the update part, there is a tool built around PyInstaller
+called `PyUpdater <https://www.pyupdater.org/>`_ which enables
+a simple mechanism to ship applications updates.
+
+On top of all these features, including also a nice interface
+that allows the user to install the application step by step,
+or even better, provide templates to create new projects to easily
+freeze-them-up is something really beneficial for both developers
+and end-users.
+This is where `fbs <https://build-system.fman.io>`_ enters the
+game, being based on PyInstaller, but including all the nice features
+we previously mentioned.
+
+Here you can find a set of tutorials on how to use the previously
+described tools.
+
+.. note:: Deployment is possible only in Qt for Python 5.12.2
+
+.. toctree::
+    :name: mastertoc
+    :maxdepth: 2
+
+    deployment-pyinstaller.rst
+    deployment-cxfreeze.rst
+    deployment-fbs.rst