Doc: Fix sphinx warnings about indentation and linking

Change-Id: I22fc8b60d9c9209224eddbd8255f8e2b834da0ae
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>

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 <https://build-system.fman.io>`_ 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 <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.
+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 <https://www.pyinstaller.org/>`_ 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) <https://packaging.python.org/>`_.
  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 <https://build-system.fman.io/>`_,
- * `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/>`_,
+ * `fbs`_
+ * `PyInstaller <pyinstaller>`_
+ * `cx_Freeze <cxfreeze>`_
+ * `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("<font color=red size=40>Hello World!</font>")
 
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 <https://doc.qt.io/qtforpython/PySide2/QtWidgets/QAbstractButton.html#signals>`_.
 
-    .. 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 refdoc>`_.
+`Python refernce documentation <python refdoc>`_.
 
 .. _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 <https://doc.qt.io/qt-5/qtquickcontrols2-configuration.html>`_.
+   You can read more about this configuration file
+   `here <https://doc.qt.io/qt-5/qtquickcontrols2-configuration.html>`_.
 
    The final look of your application will be: