From d823a2740d4dabc925f9082f28ac9865188ec8ab Mon Sep 17 00:00:00 2001 From: Kavindra Palaraja Date: Tue, 19 Nov 2019 11:44:41 +0100 Subject: docs: More fixes on deployment and faq Change-Id: I97d7251b0d9ec024ce069f6475d7bc6be0d9d362 Reviewed-by: Friedemann Kleint --- sources/pyside2/doc/deployment-fbs.rst | 58 +++++++++++++++------------------- sources/pyside2/doc/deployment.rst | 53 +++++++++++++++---------------- sources/pyside2/doc/faq.rst | 33 +++++++++++++++++++ sources/pyside2/doc/gettingstarted.rst | 4 ++- 4 files changed, 86 insertions(+), 62 deletions(-) create mode 100644 sources/pyside2/doc/faq.rst (limited to 'sources/pyside2/doc') 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) `_. - 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) `_. + 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: -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 `_, -which is built around PyInstaller. +To create update packages, use the `PyUpdater `_, 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 `_ 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 `_ decided to properly support the port. For more + information, see ``_. + +**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 -------------------- -- cgit v1.2.3