From 4af52ffcfd89a636eff09a500836e14a7ad4d877 Mon Sep 17 00:00:00 2001 From: Venugopal Shivashankar Date: Wed, 30 Oct 2019 15:26:17 +0100 Subject: Doc: Fix sphinx warnings about indentation and linking Change-Id: I22fc8b60d9c9209224eddbd8255f8e2b834da0ae Reviewed-by: Cristian Maureira-Fredes Reviewed-by: Friedemann Kleint --- sources/pyside2/doc/deployment-fbs.rst | 16 ++- sources/pyside2/doc/deployment-pyinstaller.rst | 9 +- sources/pyside2/doc/deployment.rst | 29 +++-- sources/pyside2/doc/modules.rst | 2 +- .../pyside2/doc/tutorials/basictutorial/qml.rst | 8 +- .../doc/tutorials/basictutorial/uifiles.rst | 31 +++-- .../doc/tutorials/basictutorial/widgets.rst | 12 +- .../doc/tutorials/datavisualize/filter_data.rst | 1 - .../pyside2/doc/tutorials/expenses/expenses.rst | 141 +++++++++++---------- .../pyside2/doc/tutorials/portingguide/index.rst | 6 +- .../tutorials/qmlintegration/qmlintegration.rst | 12 +- 11 files changed, 149 insertions(+), 118 deletions(-) diff --git a/sources/pyside2/doc/deployment-fbs.rst b/sources/pyside2/doc/deployment-fbs.rst index 6375da61e..311c78ac7 100644 --- a/sources/pyside2/doc/deployment-fbs.rst +++ b/sources/pyside2/doc/deployment-fbs.rst @@ -1,15 +1,17 @@ -=============== |project| & fbs -=============== +#################### -`fbs `_ provides a powerful environment for packaging, +`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. -You can read the `official tutorial `_ for more -details on how to use `fbs`, or check the -`documentation `_ for a complete set of features and -options. +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. + +.. _fbs tutorial: https://github.com/mherrmann/fbs-tutorial + +.. _fbs manual: https://build-system.fman.io/manual/ Preparation =========== diff --git a/sources/pyside2/doc/deployment-pyinstaller.rst b/sources/pyside2/doc/deployment-pyinstaller.rst index 53335ee89..c9c7b09fd 100644 --- a/sources/pyside2/doc/deployment-pyinstaller.rst +++ b/sources/pyside2/doc/deployment-pyinstaller.rst @@ -1,6 +1,5 @@ -======================= |project| & PyInstaller -======================= +####################### `PyInstaller `_ lets you freeze your python application into a stand-alone executable. @@ -143,9 +142,9 @@ 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 +A recent problem of PyInstaller is the Python 2 release, that is +v2.7.16. This Python version creates a problem that is known from +Python 3 as a `Tcl/Tk` problem. It rarely shows up in Python 3 as `Tcl/Tk` is seldom used with `PyInstaller. On Python 2.7.16, this problem is very much visible, as many are diff --git a/sources/pyside2/doc/deployment.rst b/sources/pyside2/doc/deployment.rst index eb8d77b0d..c81e85c61 100644 --- a/sources/pyside2/doc/deployment.rst +++ b/sources/pyside2/doc/deployment.rst @@ -1,6 +1,5 @@ -========== 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 @@ -11,12 +10,23 @@ Here are a few distribution options that you could use: 2. Building a proper `Python package (wheel) `_. 3. Freezing the application into a single binary file or a directory. +.. _fbs: https://build-system.fman.io/ + +.. _pyinstaller: https://www.pyinstaller.org/ + +.. _cxfreeze: https://anthony-tuininga.github.io/cx_Freeze/ + +.. _py2exe: http://www.py2exe.org/ + +.. _py2app: https://py2app.readthedocs.io/en/latest/ + If you choose the **third** option, consider using one of these tools: - * `fbs `_, - * `PyInstaller `_, - * `cx_Freeze `_, - * `py2exe `_, - * `py2app `_, + * `fbs`_ + * `PyInstaller `_ + * `cx_Freeze `_ + * `py2exe`_ + * `py2app`_ + |project| is a cross-platform framework, so we would like to focus on solutions that work on the three @@ -53,8 +63,9 @@ 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. -.. note:: Deployment is supported only from Qt for Python 5.12.2 and -later. +.. note:: + + Deployment is supported only from Qt for Python 5.12.2 and later. .. toctree:: :name: mastertoc diff --git a/sources/pyside2/doc/modules.rst b/sources/pyside2/doc/modules.rst index 6741b465d..d9accd664 100644 --- a/sources/pyside2/doc/modules.rst +++ b/sources/pyside2/doc/modules.rst @@ -5,7 +5,7 @@ Qt Modules :hidden: :glob: - PySide2/Qt** + PySide2/Qt*/* .. list-table:: :widths: 150, 150 diff --git a/sources/pyside2/doc/tutorials/basictutorial/qml.rst b/sources/pyside2/doc/tutorials/basictutorial/qml.rst index 81583096b..fb168410a 100644 --- a/sources/pyside2/doc/tutorials/basictutorial/qml.rst +++ b/sources/pyside2/doc/tutorials/basictutorial/qml.rst @@ -14,7 +14,9 @@ that loads the QML file. To make things easier, let's save both files in the same directory. Here is a simple QML file called `view.qml`: -:: + +.. code-block:: javascript + import QtQuick 2.0 Rectangle { @@ -39,7 +41,9 @@ is the Rectangle in this case. Now, let's see how the code looks on the PySide2. Let's call it `main.py`: -:: + +.. code-block:: python + from PySide2.QtWidgets import QApplication from PySide2.QtQuick import QQuickView from PySide2.QtCore import QUrl diff --git a/sources/pyside2/doc/tutorials/basictutorial/uifiles.rst b/sources/pyside2/doc/tutorials/basictutorial/uifiles.rst index b00437bcb..a45bfc18c 100644 --- a/sources/pyside2/doc/tutorials/basictutorial/uifiles.rst +++ b/sources/pyside2/doc/tutorials/basictutorial/uifiles.rst @@ -78,14 +78,12 @@ Generating a Python class Another option to interact with a **UI file** is to generate a Python class from it. This is possible thanks to the `pyside2-uic` tool. -To use this tool, you need to run the following command on a console: -:: +To use this tool, you need to run the following command on a console:: pyside2-uic mainwindow.ui > ui_mainwindow.py We redirect all the output of the command to a file called `ui_mainwindow.py`, -which will be imported directly: -:: +which will be imported directly:: from ui_mainwindow import Ui_MainWindow @@ -93,7 +91,8 @@ Now to use it, we should create a personalized class for our widget to **setup** this generated design. To understand the idea, let's take a look at the whole code: -:: + +.. code-block:: python import sys from PySide2.QtWidgets import QApplication, QMainWindow @@ -118,26 +117,32 @@ What is inside the *if* statement is already known from the previous examples, and our new basic class contains only two new lines that are in charge of loading the generated python class from the UI file: -:: + +.. code-block:: python self.ui = Ui_MainWindow() self.ui.setupUi(self) -.. note:: You must run `pyside2-uic` again every time you make changes -to the **UI file**. +.. note:: + + You must run `pyside2-uic` again every time you make changes + to the **UI file**. Loading it directly ==================== To load the UI file directly, we will need a class from the **QtUiTools** module: -:: + +.. code-block:: python from PySide2.QtUiTools import QUiLoader The `QUiLoader` lets us load the **ui file** dynamically and use it right away: -:: + +.. code-block:: python + ui_file = QFile("mainwindow.ui") ui_file.open(QFile.ReadOnly) @@ -146,7 +151,8 @@ and use it right away: window.show() The complete code of this example looks like this: -:: + +.. code-block:: python # File: main.py import sys @@ -169,6 +175,7 @@ The complete code of this example looks like this: Then to execute it we just need to run the following on a command prompt: -:: + +.. code-block:: python python main.py diff --git a/sources/pyside2/doc/tutorials/basictutorial/widgets.rst b/sources/pyside2/doc/tutorials/basictutorial/widgets.rst index c864e3d47..41e474227 100644 --- a/sources/pyside2/doc/tutorials/basictutorial/widgets.rst +++ b/sources/pyside2/doc/tutorials/basictutorial/widgets.rst @@ -5,7 +5,9 @@ As with any other programming framework, you start with the traditional "Hello World" program. Here is a simple example of a Hello World application in PySide2: -:: + +.. code-block:: python + import sys from PySide2.QtWidgets import QApplication, QLabel @@ -22,13 +24,17 @@ After the imports, you create a `QApplication` instance. As Qt can receive arguments from command line, you may pass any argument to the QApplication object. Usually, you don't need to pass any arguments so you can leave it as is, or use the following approach: -:: + +.. code-block:: python + app = QApplication([]) After the creation of the application object, we have created a `QLabel` object. A `QLabel` is a widget that can present text (simple or rich, like html), and images: -:: + +.. code-block:: python + # This HTML approach will be valid too! label = QLabel("Hello World!") diff --git a/sources/pyside2/doc/tutorials/datavisualize/filter_data.rst b/sources/pyside2/doc/tutorials/datavisualize/filter_data.rst index f54ba217c..b06b2fa15 100644 --- a/sources/pyside2/doc/tutorials/datavisualize/filter_data.rst +++ b/sources/pyside2/doc/tutorials/datavisualize/filter_data.rst @@ -23,7 +23,6 @@ The following script filters and formats the CSV data as described earlier: .. literalinclude:: datavisualize2/main.py :language: python :linenos: - :emphasize-lines: 44,47-69 :lines: 40- Now that you have a tuple of QDateTime and float data, try improving the diff --git a/sources/pyside2/doc/tutorials/expenses/expenses.rst b/sources/pyside2/doc/tutorials/expenses/expenses.rst index c34d18669..a19cec5c3 100644 --- a/sources/pyside2/doc/tutorials/expenses/expenses.rst +++ b/sources/pyside2/doc/tutorials/expenses/expenses.rst @@ -31,7 +31,8 @@ Empty window The base structure for a `QApplication` is located inside the `if __name__ == "__main__":` code block. - .. code:: +.. code-block:: python + :dedent: 4 if __name__ == "__main__": app = QApplication([]) @@ -41,17 +42,17 @@ code block. Now, to start the development, create an empty window called `MainWindow`. You could do that by defining a class that inherits from `QMainWindow`. - .. literalinclude:: steps/01-expenses.py - :linenos: - :lines: 45-59 - :emphasize-lines: 45-48 +.. literalinclude:: steps/01-expenses.py + :linenos: + :lines: 45-59 + :emphasize-lines: 1-4 Now that our class is defined, create an instance of it and call `show()`. - .. literalinclude:: steps/01-expenses.py - :linenos: - :lines: 45-59 - :emphasize-lines: 54-56 +.. literalinclude:: steps/01-expenses.py + :linenos: + :lines: 45-59 + :emphasize-lines: 10-12 Menu bar -------- @@ -59,10 +60,10 @@ Menu bar Using a `QMainWindow` gives some features for free, among them a *menu bar*. To use it, you need to call the method `menuBar()` and populate it inside the `MainWindow` class. - .. literalinclude:: steps/02-expenses.py - :linenos: - :lines: 46-58 - :emphasize-lines: 51 +.. literalinclude:: steps/02-expenses.py + :linenos: + :lines: 46-58 + :emphasize-lines: 6 Notice that the code snippet adds a *File* menu with the *Exit* option only. @@ -72,14 +73,14 @@ First signal/slot connection The *Exit* option must be connected to a slot that triggers the application to exit. The main idea to achieve this, is the following: - .. code:: +.. code-block:: python element.signal_name.connect(slot_name) All the interface's elements could be connected through signals to certain slots, in the case of a `QAction`, the signal `triggered` can be used: - .. code:: +.. code-block:: python exit_action.triggered.connect(slot_name) @@ -87,10 +88,10 @@ in the case of a `QAction`, the signal `triggered` can be used: `QApplication.quit()`. If we put all these concepts together you will end up with the following code: - .. literalinclude:: steps/03-expenses.py - :linenos: - :lines: 56-65 - :emphasize-lines: 59, 63-65 +.. literalinclude:: steps/03-expenses.py + :linenos: + :lines: 56-65 + :emphasize-lines: 4, 8-10 Notice that the decorator `@Slot()` is required for each slot you declare to properly register them. Slots are normal functions, but the main difference is that they @@ -105,15 +106,15 @@ This central widget could be another class derived from `QWidget`. Additionally, you will define example data to visualize later. - .. literalinclude:: steps/04-expenses.py - :linenos: - :lines: 46-53 +.. literalinclude:: steps/04-expenses.py + :linenos: + :lines: 46-53 With the `Widget` class in place, modify `MainWindow`'s initialization code - .. literalinclude:: steps/04-expenses.py - :linenos: - :lines: 80-84 +.. literalinclude:: steps/04-expenses.py + :linenos: + :lines: 80-84 Window layout ------------- @@ -124,13 +125,13 @@ goal of creating an expenses application. After declaring the example data, you can visualize it on a simple `QTableWidget`. To do so, you will add this procedure to the `Widget` constructor. - .. warning:: Only for the example purpose a QTableWidget will be used, - but for more performance-critical applications the combination - of a model and a QTableView is encouraged. +.. warning:: Only for the example purpose a QTableWidget will be used, + but for more performance-critical applications the combination + of a model and a QTableView is encouraged. - .. literalinclude:: steps/05-expenses.py - :linenos: - :lines: 48-73 +.. literalinclude:: steps/05-expenses.py + :linenos: + :lines: 48-73 As you can see, the code also includes a `QHBoxLayout` that provides the container to place widgets horizontally. @@ -141,9 +142,9 @@ columns that will be used, and to *stretch* the content to use the whole `Widget The last line of code refers to *filling the table**, and the code to perform that task is displayed below. - .. literalinclude:: steps/05-expenses.py - :linenos: - :lines: 75-81 +.. literalinclude:: steps/05-expenses.py + :linenos: + :lines: 75-81 Having this process on a separate method is a good practice to leave the constructor more readable, and to split the main functions of the class in independent processes. @@ -159,17 +160,17 @@ application. To distribute these input lines and buttons, you will use a `QVBoxLayout` that allows you to place elements vertically inside a layout. - .. literalinclude:: steps/06-expenses.py - :linenos: - :lines: 64-80 +.. literalinclude:: steps/06-expenses.py + :linenos: + :lines: 64-80 Leaving the table on the left side and these newly included widgets to the right side will be just a matter to add a layout to our main `QHBoxLayout` as you saw in the previous example: - .. literalinclude:: steps/06-expenses.py - :linenos: - :lines: 42-47 +.. literalinclude:: steps/06-expenses.py + :linenos: + :lines: 42-47 The next step will be connecting those new buttons to slots. @@ -181,19 +182,19 @@ Each `QPushButton` have a signal called *clicked*, that is emitted when you clic This will be more than enough for this example, but you can see other signals in the `official documentation `_. - .. literalinclude:: steps/07-expenses.py - :linenos: - :lines: 92-95 +.. literalinclude:: steps/07-expenses.py + :linenos: + :lines: 92-95 As you can see on the previous lines, we are connecting each *clicked* signal to different slots. In this example slots are normal class methods in charge of perform a determined task associated with our buttons. It is really important to decorate each method declaration with a `@Slot()`, in that way PySide2 knows internally how to register them into Qt. - .. literalinclude:: steps/07-expenses.py - :linenos: - :lines: 1000-129 - :emphasize-lines: 101,115,127 +.. literalinclude:: steps/07-expenses.py + :linenos: + :lines: 100-129 + :emphasize-lines: 2,16,28 Since these slots are methods, we can access the class variables, like our `QTableWidget` to interact with it. @@ -225,15 +226,15 @@ the current content of the `QLineEdit`. You can connect two different object's signal to the same slot, and this will be the case for your current application: - .. literalinclude:: steps/08-expenses.py - :linenos: - :lines: 99-100 +.. literalinclude:: steps/08-expenses.py + :linenos: + :lines: 99-100 The content of the *check_disable* slot will be really simple: - .. literalinclude:: steps/08-expenses.py - :linenos: - :lines: 119-124 +.. literalinclude:: steps/08-expenses.py + :linenos: + :lines: 119-124 You have two options, write a verification based on the current value of the string you retrieve, or manually get the whole content of both @@ -253,17 +254,17 @@ OK, but you can accomplish more by representing the data graphically. First you will include an empty `QChartView` placeholder into the right side of your application. - .. literalinclude:: steps/09-expenses.py - :linenos: - :lines: 66-68 +.. literalinclude:: steps/09-expenses.py + :linenos: + :lines: 66-68 Additionally the order of how you include widgets to the right `QVBoxLayout` will also change. - .. literalinclude:: steps/09-expenses.py - :linenos: - :lines: 81-91 - :emphasize-lines: 89 +.. literalinclude:: steps/09-expenses.py + :linenos: + :lines: 81-91 + :emphasize-lines: 9 Notice that before we had a line with `self.right.addStretch()` to fill up the vertical space between the *Add* and the *Clear* buttons, @@ -277,18 +278,18 @@ Full application For the final step, you will need to connect the *Plot* button to a slot that creates a chart and includes it into your `QChartView`. - .. literalinclude:: steps/10-expenses.py - :linenos: - :lines: 103-109 - :emphasize-lines: 106 +.. literalinclude:: steps/10-expenses.py + :linenos: + :lines: 103-109 + :emphasize-lines: 6 That is nothing new, since you already did it for the other buttons, but now take a look at how to create a chart and include it into your `QChartView`. - .. literalinclude:: steps/10-expenses.py - :linenos: - :lines: 139-151 +.. literalinclude:: steps/10-expenses.py + :linenos: + :lines: 139-151 The following steps show how to fill a `QPieSeries`: @@ -305,9 +306,9 @@ your newly created chart to the `QChartView`. The application will look like this: - .. image:: expenses_tool.png +.. image:: expenses_tool.png And now you can see the whole code: - .. literalinclude:: main.py - :linenos: +.. literalinclude:: main.py + :linenos: diff --git a/sources/pyside2/doc/tutorials/portingguide/index.rst b/sources/pyside2/doc/tutorials/portingguide/index.rst index 8fd4c431a..aabf4b19f 100644 --- a/sources/pyside2/doc/tutorials/portingguide/index.rst +++ b/sources/pyside2/doc/tutorials/portingguide/index.rst @@ -66,7 +66,7 @@ In this example, ``func()`` would treat ``var`` as a local name without the ``global`` statement. This would lead to a ``NameError`` in the ``value is None`` handling, on accessing ``var``. For more information about this, see - `Python refernce documentation `_. +`Python refernce documentation `_. .. _python refdoc: https://docs.python.org/3/reference/simple_stmts.html#the-global-statement @@ -128,7 +128,8 @@ Here are a few important ones that you must be aware of: equivalent for this is the `@Slot`` decorator just before the function definition. This is necessary to register the slots with the QtMetaObject. -* **QString, QVariant, and other types**: +* **QString, QVariant, and other types** + - Qt for Python does not provide access to QString and QVariant. You must use Python's native types instead. - QChar and QStringRef are represented as Python strings, @@ -141,6 +142,7 @@ Here are a few important ones that you must be aware of: renamed to bin_(), hex_(), and oct_() respectively. This should avoid name conflicts with Python's built-in functions. + * **QByteArray**: A QByteArray is treated as a list of bytes without encoding. The equivalent type in Python varies; Python 2 uses "str" type, whereas Python 3 uses diff --git a/sources/pyside2/doc/tutorials/qmlintegration/qmlintegration.rst b/sources/pyside2/doc/tutorials/qmlintegration/qmlintegration.rst index d82e76246..62336ee81 100644 --- a/sources/pyside2/doc/tutorials/qmlintegration/qmlintegration.rst +++ b/sources/pyside2/doc/tutorials/qmlintegration/qmlintegration.rst @@ -31,7 +31,7 @@ application and PySide2 integration: .. literalinclude:: main.py :linenos: :lines: 98-108 - :emphasize-lines: 103,107 + :emphasize-lines: 6,9 Notice that we specify the name of the context property, **con**, and also we explicitly load our QML file. @@ -47,7 +47,7 @@ application and PySide2 integration: .. literalinclude:: view.qml :linenos: :lines: 85-93 - :emphasize-lines: 89-91 + :emphasize-lines: 5-7 The properties *Italic*, *Bold*, and *Underline* are mutually exclusive, this means only one can be active at any time. @@ -64,7 +64,7 @@ application and PySide2 integration: .. literalinclude:: main.py :linenos: :lines: 79-84 - :emphasize-lines: 82,84 + :emphasize-lines: 4,6 Returning *True* or *False* allows you to activate and deactivate the properties of the QML UI elements. @@ -98,10 +98,10 @@ application and PySide2 integration: .. literalinclude:: main.py :linenos: :lines: 41-48 - :emphasize-lines: 48 + :emphasize-lines: 8 - You can read more about this configuration file - `here `_. + You can read more about this configuration file + `here `_. The final look of your application will be: -- cgit v1.2.3