docs: More fixes on deployment and faq

Change-Id: I97d7251b0d9ec024ce069f6475d7bc6be0d9d362
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>

4 files changed, 86 insertions, 62 deletions

diff --git a/sources/pyside2/doc/deployment-fbs.rst b/sources/pyside2/doc/deployment-fbs.rst
index 0a75f2c4d..a90b4993b 100644
--- a/sources/pyside2/doc/deployment-fbs.rst
+++ b/sources/pyside2/doc/deployment-fbs.rst
@@ -1,48 +1,43 @@
 |project| & fbs
 ####################
 
-``fbs`` provides a powerful environment for packaging,
-creating installers, and signing your application. It also lets you manage updates to
-your application. As it is based on PyInstaller, it supports Linux, macOS, and Windows.
+`fbs`_ provides a powerful environment for packaging, creating installers, and signing your
+application. It also lets you manage updates to your application. Since `fbs` is based on
+PyInstaller, it supports Linux, macOS, and Windows.
 
-You can read the `fbs tutorial`_ for more details about how to use
-`fbs`, or check out the `fbs manual`_ for a complete set of features
-and options.
+For more details, see the `fbs tutorial`_ and the `fbs manual`_.
 
+.. _fbs: https://build-system.fman.io/
 .. _fbs tutorial: https://github.com/mherrmann/fbs-tutorial
-
 .. _fbs manual: https://build-system.fman.io/manual/
 
 Preparation
 ===========
 
-Installing `fbs` (>= 0.7.6) can be done via **pip**::
+Installing `fbs`_ (>= 0.7.6) is done via **pip**::
 
     pip install fbs
 
-If you are using a virtual environment, remember to activate it before
-installing it.
+If you're using a virtual environment, remember to activate it before installing `fbs`_.
 
-After the installation, you will be able to use the `fbs` executable.
+After the installation, you can use the `fbs`_ executable.
 
 Starting a new project
 ======================
 
-`fbs` provides nice features that lets you create a base
-project structure by executing the following command::
+`fbs`_ provides useful features for you to create a base project structure with the following
+command::
 
     fbs startproject
 
-This command prompts you to answer a few questions to configure the details
-of your project, like:
+This command prompts you to answer a few questions to configure the details of your project, like:
 
  * Application name
  * Author name
  * Qt bindings (PySide2 or PyQt5)
  * Bundle indentified (for macOS)
 
-After it finishes, you will have a `src/` directory that
-contains the following structure::
+Afterwards, you have a `src/` directory that contains the following structure::
 
     └── src
         ├── build
@@ -54,11 +49,10 @@ contains the following structure::
             │   └── mac
             └── python
 
-Inside the `settings` directory, you will find a couple of `json` files
-that can be edited to include more information about your project.
+Inside the `settings` directory, there are a few JSON files that can be edited to include more
+information about your project.
 
-The `main` file will be under the `python` directory, and its content
-by default is::
+The `main` file is in the `python` directory, and its default content is::
 
     from fbs_runtime.application_context import ApplicationContext
     from PySide2.QtWidgets import QMainWindow
@@ -73,33 +67,31 @@ by default is::
         exit_code = appctxt.app.exec_()      # 2. Invoke appctxt.app.exec_()
         sys.exit(exit_code)
 
-This example shows an empty `QMainWindow`. You can run it using the
-following command::
+This example shows an empty `QMainWindow`. You can run it using the following command::
 
     fbs run
 
 Freezing the application
 ========================
 
-Once you verify that the application is properly working,
-you can continue with the freezing process using the following
-command::
+Once you've verified that the application is working properly, you can continue with the freezing
+process using the following command::
 
     fbs freeze
 
-After the process finishes, you will get a message stating the location
-of your executable. For example::
+After the process completes, you see a message stating the location of your executable. For
+example::
 
     Done. You can now run `target/MyApp/MyApp`. If that doesn't work, see
     https://build-system.fman.io/troubleshooting.
 
 
-You can now try running the application, which will result in the same
-window that you saw with the `fbs run` command::
+Now, you can try to run the application. The result is the same window as the one you saw with the
+`fbs run` command::
 
     cd target/MyApp/
     ./MyApp
 
-.. note:: This is the case for Linux. For other platforms like macOS,
-   you need to enter the directory: `target/MyApp.app/Contents/macOS`,
-   and for Windows find the `MyApp.exe` executable.
+.. note:: This is the case for Linux. For other platforms like macOS, you need to enter the
+   directory: `target/MyApp.app/Contents/macOS`. For Windows, you need to find the `MyApp.exe`
+   executable.
diff --git a/sources/pyside2/doc/deployment.rst b/sources/pyside2/doc/deployment.rst
index f33e3cac0..78d6058da 100644
--- a/sources/pyside2/doc/deployment.rst
+++ b/sources/pyside2/doc/deployment.rst
@@ -1,16 +1,19 @@
 |project| 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.
 
-Here are a few distribution options that you could use:
- 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 into a single binary file or a directory.
+Deploying or freezing an application is an important part of a Python project,
+this means to bundle all required resources so that the application finds everything it needs to
+be able to run on a client's machine.
+However, because most large projects aren't based on a single Python file, distributing these
+applications can be a challenge.
 
-If you choose the **third** option, consider using one of these tools:
+Here are a few distribution options that you can use:
+ 1. Send a normal ZIP file with the application's content.
+ 2. Build a proper `Python package (wheel) <https://packaging.python.org/>`_.
+ 3. Freeze the application into a single binary file or directory.
+
+If you choose Option 3, consider using one of these tools:
  * `fbs`_
  * `PyInstaller`_
  * `cx_Freeze`_
@@ -23,11 +26,10 @@ If you choose the **third** option, consider using one of these tools:
 .. _py2exe: http://www.py2exe.org/
 .. _py2app: https://py2app.readthedocs.io/en/latest/
 
-|project| is a cross-platform framework,
-so we would like to focus on solutions that work on the three
-major platforms supported by Qt: Linux, macOS, and Windows.
-The following table summarizes the platform support for those packaging
-tools:
+Since |project| is a cross-platform framework, we focus on solutions for the three major
+platforms that Qt supports: Windows, Linux, and macOS.
+
+The following table summarizes the platform support for those packaging tools:
 
 .. raw:: html
 
@@ -80,29 +82,24 @@ tools:
       </tbody>
     </table>
 
-According to this table, only *fbs*, *cx_Freeze*, and *PyInstaller*
-meets our cross-platform requirement.
+Notice that only *fbs*, *cx_Freeze*, and *PyInstaller* meet our cross-platform requirement.
 
-As these are command-line tools, it could be hard to include
-resources to your application, such as images, icons, and
-meta-information. This means, you will need special hooks
-or scripts to handle them before adding to the package.
-In addition to this, these tools does not offer a mechanism
-to update your application packages.
+Since these are command-line tools, you'll need special hooks or scripts to handle resources
+such as images, icons, and meta-information, before adding them to your package. Additionally,
+these tools don't offer a mechanism to update your application packages.
 
-To create update packages, use the `PyUpdater <https://www.pyupdater.org/>`_,
-which is built around PyInstaller.
+To create update packages, use the `PyUpdater <https://www.pyupdater.org/>`_, which is a tool
+built around PyInstaller.
 
-The `fbs`_ tool offers a nice UI
-that allows the user to install the application step-by-step.
-
-Here you can find a set of tutorials on how to use the previously
-described tools.
+The `fbs <https://build-system.fman.io>`_ tool offers a nice UI for the user to install the
+application step-by-step.
 
 .. note::
 
    Deployment is supported only from Qt for Python 5.12.2 and later.
 
+Here's a set of tutorials on how to use these tools:
+
 .. toctree::
     :name: mastertoc
     :maxdepth: 2
diff --git a/sources/pyside2/doc/faq.rst b/sources/pyside2/doc/faq.rst
new file mode 100644
index 000000000..f1aa3ebcc
--- /dev/null
+++ b/sources/pyside2/doc/faq.rst
@@ -0,0 +1,33 @@
+Frequently Asked Questions
+==========================
+
+**When did The Qt Company adopt PySide2?**
+  In April 2016 `The Qt Company <https://qt.io>`_ decided to properly support the port. For more
+  information, see `<https://groups.google.com/forum/#!topic/pyside-dev/pqwzngAGLWE>`_.
+
+**Why use PySide2 and not PySide?**
+  Since PySide was developed for Qt 4, we now use PySide2 to imply that it is for a newer version,
+  after it was ported to support Qt 5.
+
+**Where I can find information about the old PySide project?**
+  The project's old wiki page is available on PySide, but the project is now deprecated and not
+  supported.
+
+**There are three wheels (pyside2, shiboken2, and shiboken2_generator), what's the difference?**
+
+  Before the official release, everything was in one big wheel, so it made sense to split these
+  into separate wheels, each for the major projects currently in development:
+
+   * **pyside2**: contains all the PySide2 modules to use the Qt framework; also depends on the
+     shiboken2 module.
+   * **shiboken2**: contains the shiboken2 module with helper functions for PySide2.
+   * **shiboken2_generator**: contains the generator binary that can work with a C++ project and a
+     typesystem to generate Python bindings.
+     If you want to generate bindings for a Qt/C++ project, there won't be any linking to the Qt
+     shared libraries; you need to do this by hand. We recommend building PySide2 from scratch
+     to have everything properly linked.
+
+**Why is the shiboken2_generator not installed automatically?**
+  It's not necessary to install the shiboken2_generator to use PySide2. The package is a result of
+  the wheel splitting process. To use the generator, it's recommended to build it from scratch to
+  have the proper Qt linking.
diff --git a/sources/pyside2/doc/gettingstarted.rst b/sources/pyside2/doc/gettingstarted.rst
index 5d3ea3c31..d7a138b20 100644
--- a/sources/pyside2/doc/gettingstarted.rst
+++ b/sources/pyside2/doc/gettingstarted.rst
@@ -6,9 +6,11 @@ with ``pip`` you need to run::
 
     pip install pyside2
 
-for more details, refer to our `Quick Start`_ guide.
+for more details, refer to our `Quick Start`_ guide. Additionally, you can
+check the `FAQ`_ related to the project.
 
 .. _Quick Start: quickstart.html
+.. _FAQ: faq.html
 
 General Requirements
 --------------------