diff options
author | Venugopal Shivashankar <Venugopal.Shivashankar@qt.io> | 2019-06-11 16:23:10 +0200 |
---|---|---|
committer | Venugopal Shivashankar <Venugopal.Shivashankar@qt.io> | 2019-06-12 11:26:48 +0200 |
commit | b4098737b13c91ca85b69362426f0f30768c49b1 (patch) | |
tree | 887b093f9f7feaa05e0e6ee82698711b769d5bc5 /sources | |
parent | 086736b4d51e004a633947fe612bfdf0cd3478b1 (diff) |
Doc: Minor language edits
- reordered a few sentences
- removed a few redundant bits
Change-Id: I111dc51b7912a056ec8d9dc3bc765e9d374b6060
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
Diffstat (limited to 'sources')
-rw-r--r-- | sources/pyside2/doc/deployment-cxfreeze.rst | 30 | ||||
-rw-r--r-- | sources/pyside2/doc/deployment-fbs.rst | 37 | ||||
-rw-r--r-- | sources/pyside2/doc/deployment-pyinstaller.rst | 80 |
3 files changed, 76 insertions, 71 deletions
diff --git a/sources/pyside2/doc/deployment-cxfreeze.rst b/sources/pyside2/doc/deployment-cxfreeze.rst index 40b65621b..f0a71ca80 100644 --- a/sources/pyside2/doc/deployment-cxfreeze.rst +++ b/sources/pyside2/doc/deployment-cxfreeze.rst @@ -2,10 +2,9 @@ |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. - +`cx_Freeze <https://anthony-tuininga.github.io/cx_Freeze/>`_ lets you +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 @@ -15,7 +14,7 @@ if you find any, or contributing to `their development <https://bitbucket.org/an Preparation =========== -Installing `cx_Freeze` can be done via **pip**:: +Installing `cx_Freeze` can be done using **pip**:: pip install cx_freeze @@ -34,7 +33,7 @@ There are three options to work with `cx_Freeze`: 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. +The following sections cover the first two use cases. Creating an example ------------------- @@ -83,15 +82,16 @@ Now, consider the following simple script, named `hello.py`:: Using `cxfreeze` executable --------------------------- -The command line to proceed will look like this:: +Now that we have an application, try freezing it with the following +command:: cxfreeze hello.py -This command will create a `dist/` directory that will contain the -executable and a `lib/` directory including all the shared libraries. +This command creates a `dist/` directory containing the executable. +and a `lib/` directory containing all the shared libraries. -To launch the application, you need to just go to the `dist/` directory -and execute the file:: +To launch the application, go to the `dist/` directory and execute +the file:: cd dist/ ./main @@ -100,7 +100,7 @@ and execute the file:: Using a setuptools script ------------------------- -For this process, you will need an additional script called `setup.py`:: +For this process, you need an additional script called `setup.py`:: import sys from cx_Freeze import setup, Executable @@ -110,18 +110,18 @@ For this process, you will need an additional script called `setup.py`:: description = "My GUI App", executables = [Executable("hello.py")]) -After that, you need to build the project using it:: +Now, build the project using it:: python setup.py build -This step will create a `build/` directory with the following structure:: +This step creates 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 +The first directory inside `build/` depends 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:: diff --git a/sources/pyside2/doc/deployment-fbs.rst b/sources/pyside2/doc/deployment-fbs.rst index ff489f745..6375da61e 100644 --- a/sources/pyside2/doc/deployment-fbs.rst +++ b/sources/pyside2/doc/deployment-fbs.rst @@ -3,8 +3,8 @@ =============== `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. +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. You can read the `official tutorial <https://github.com/mherrmann/fbs-tutorial>`_ for more details on how to use `fbs`, or check the @@ -26,12 +26,12 @@ 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 +`fbs` provides nice features that lets you 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 +This command prompts you to answer a few questions to configure the details of your project, like: * Application name @@ -39,8 +39,8 @@ of your project, like: * 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:: +After it finishes, you will have a `src/` directory that +contains the following structure:: └── src ├── build @@ -52,10 +52,11 @@ will contain the following structure:: │ └── 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. +Inside the `settings` directory, you will find a couple of `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 will be under the `python` directory, and its content +by default is:: from fbs_runtime.application_context import ApplicationContext from PySide2.QtWidgets import QMainWindow @@ -70,7 +71,8 @@ The main file will be under the `python` directory, and its content by default i exit_code = appctxt.app.exec_() # 2. Invoke appctxt.app.exec_() sys.exit(exit_code) -The example will show an empty `QMainWindow`, and you can execute it by running:: +This example shows an empty `QMainWindow`. You can run it using the +following command:: fbs run @@ -78,23 +80,24 @@ Freezing the application ======================== Once you verify that the application is properly working, -you can continue with the freezing process:: +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, e.g.:: +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. -Then executing the application will result in the same window -you saw with the `fbs run` command:: +You can now try running the application, which will result in the same +window that 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. +.. 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. diff --git a/sources/pyside2/doc/deployment-pyinstaller.rst b/sources/pyside2/doc/deployment-pyinstaller.rst index f361daf4a..7a720f558 100644 --- a/sources/pyside2/doc/deployment-pyinstaller.rst +++ b/sources/pyside2/doc/deployment-pyinstaller.rst @@ -2,12 +2,12 @@ |project| & PyInstaller ======================= -`PyInstaller <https://www.pyinstaller.org/>`_ allows you to freeze your python +`PyInstaller <https://www.pyinstaller.org/>`_ lets you 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|. +Python modules, for example: |pymodname|. You can read the `official documentation <https://www.pyinstaller.org/documentation.html>`_ to clarify any further question, and remember to contribute to @@ -17,7 +17,7 @@ by filing issues if you find any, or contributing to their development. Preparation =========== -Installing `PyInstaller` can be done via **pip**:: +Installing `PyInstaller` can be done using **pip**:: pip install pyinstaller @@ -26,12 +26,11 @@ 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`, include the whole path when executing `pyinstaller`. -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. +.. warning:: If you already have a PySide2 or Shiboken2 version installed in your + system path, PyInstaller will pick them instead of your virtual environment + version. Freezing an application ======================= @@ -41,13 +40,12 @@ 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. +and to place it in a directory containing the libraries. Additionally, for Windows you can enable opening a console during the -execution with the option `-c` (or equivalent `--console` or `--nowindowed`). +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`). +on macOS and Windows with the option, `-w` (or equivalent `--windowed` or `--noconsole`). Creating an example ------------------- @@ -93,32 +91,33 @@ Now, consider the following simple script, named `hello.py`:: sys.exit(app.exec_()) -Since it has a UI, we will use the `--windowed` option. +As it has a UI, you will use the `--windowed` option. -The command line to proceed will look like this:: +The command line to proceed looks 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`. +This process creates a `dist/` and `build/` directory. +The application executable and the required shared libraries are +placed in `dist/MyApplication`. -To execute the frozen application you can go inside `dist/MyApplication` and +To run the application you can go to `dist/MyApplication` and execute the program:: cd dist/MyApplication/ ./MyApplication -.. note:: The directory inside `dist/` and the executable will have the same name. +.. 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 +If you prefer to have everything bundled into one executable, +without the shared libraries next to it, 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:: +This process takes a bit longer, but in the end you will have one +executable in the `dist/` directory:: cd dist/ ./MyApplication @@ -131,26 +130,29 @@ Current Caveats To Be Aware Of PyInstaller Problem ------------------- -As already mentioned, `PyInstaller` will pick a system installation of PySide2 or -Shiboken2 instead of your virtualenv version without notice, if it exists. -This may be no problem if those PySide2 or shiboken2 versions are the same. - -If you are working with different versions, this can result in frustrating sessions, -when you think you are testing a new version, but `PyInstaller` -is silently working with a different, older version. +As already mentioned, `PyInstaller` will pick a system installation +of PySide2 or Shiboken2 instead of your virtualenv version without +notice, if it exists. This may not be a problem if those two +versions are the same. +If you are working with different versions, this can result in +frustrating debugging sessions. You could think you are testing the +latest version, but `PyInstaller` could be working with an older +version. Problem with numpy in Python 2.7.16 ----------------------------------- -A recent problem of PyInstaller is the appearance of Python 2.7.16 . -This Python version creates a problem that is known from Python 3 as a `Tcl/Tk` problem. -This does rarely show up in Python 3 because `Tcl/Tk` is seldom used with `PyInstaller. +A recent problem of PyInstaller is the appearance of Python 2.7.16. +This Python version creates a problem that is known from Python 3 +as a `Tcl/Tk` problem. This does rarely show up in Python 3 because +`Tcl/Tk` is seldom used with `PyInstaller. -On Python 2.7.16, this problem is very much visible, since many people are using numpy. -For some reason, installing `numpy` creates a dependency of `Tcl/Tk`, which can -be circumvented only by explicitly excluding `Tcl/Tk` related things by adding -this line to the analysis section of the spec-file:: +On Python 2.7.16, this problem is very much visible, as many are +using numpy. For some reason, installing `numpy` creates a +dependency to `Tcl/Tk`, which can be circumvented only by explicitly +excluding `Tcl/Tk` related things by adding this line to the analysis +section of the spec-file:: excludes=['FixTk', 'tcl', 'tk', '_tkinter', 'tkinter', 'Tkinter'], @@ -162,12 +164,12 @@ o When using `PyInstaller` with `virtualenv`, make sure that there is no system installation of PySide2 or shiboken2. o Before compiling, use `pip -uninstall pyside2 shiboken2 -y` multiple times, until - none of the programs is found anymore. + none of the programs are found anymore. o Pip is usually a good tool. But to be 100 % sure, you should directly remove the PySide2 and shiboken2 folders from site-packages. o Be sure to use the right version of pip. The safest way to really run the right - pip, use the Python that you mean: Instead of the pip command, better use:: + pip, is to use the Python that you mean: Instead of the pip command, better use:: <path/to/your/>python -m pip |