Document the scriptableapplication, samplebinding examples

Add a dummy .pyproject file into the doc directory for the example
gallery script to collect it.
Convert the .md files to .rst files for the documentation.

Pick-to: 6.2
Change-Id: I87ea5b980d3d2177a7851f71462ca0b0bd0eba7e
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>

2 files changed, 93 insertions, 64 deletions

diff --git a/examples/scriptableapplication/doc/scriptableapplication.pyproject b/examples/scriptableapplication/doc/scriptableapplication.pyproject
new file mode 100644
index 000000000..eee541125
--- /dev/null
+++ b/examples/scriptableapplication/doc/scriptableapplication.pyproject
@@ -0,0 +1,9 @@
+{
+    "files": ["../main.cpp",
+              "../mainwindow.cpp",
+              "../mainwindow.h",
+              "../pythonutils.cpp",
+              "../pythonutils.h",
+              "../wrappedclasses.h",
+              "../CMakeLists.txt"]
+}
diff --git a/examples/scriptableapplication/README.md b/examples/scriptableapplication/doc/scriptableapplication.rst
index d7773c320..46a29bd2f 100644
--- a/examples/scriptableapplication/README.md
+++ b/examples/scriptableapplication/doc/scriptableapplication.rst
@@ -1,28 +1,31 @@
-# Scriptable Application
+Scriptable Application Example
+==============================
 
 This example demonstrates how to make a Qt C++ application scriptable.
 
-It has a class **MainWindow** (`mainwindow.{cpp,h}`)
-that inherits from *QMainWindow*, for which bindings are generated
+It has a class ``MainWindow`` (files ``mainwindow.cpp,h``)
+that inherits from ``QMainWindow``, for which bindings are generated
 using Shiboken.
 
-The header `wrappedclasses.h` is passed to Shiboken which generates
-class wrappers and headers in a sub directory called **AppLib/**
+The header ``wrappedclasses.h`` is passed to Shiboken which generates
+class wrappers and headers in a sub directory called ``AppLib/``
 which are linked to the application.
 
-The files `pythonutils.{cpp,h}` contain some code which binds the
-instance of **MainWindow** to a variable called **'mainWindow'** in
-the global Python namespace (`__main___`).
+The files ``pythonutils.cpp,h`` contain some code which binds the
+instance of ``MainWindow`` to a variable called ``mainWindow`` in
+the global Python namespace (``__main___``).
 It is then possible to run Python script snippets like:
 
-```python
-mainWindow.testFunction1()
-```
+.. code-block:: python
+
+    mainWindow.testFunction1()
+
 which trigger the underlying C++ function.
 
-## Building the project
+Building the project
+********************
 
-This example can be built using *CMake* or *QMake*,
+This example can be built using ``CMake`` or ``QMake``,
 but there are common requirements that you need to take into
 consideration:
 
@@ -30,9 +33,11 @@ consideration:
   is installed into the current active Python environment
   (system or virtualenv)
 * qmake has to be in your PATH:
+
   * so that CMake find_package(Qt6 COMPONENTS Core) works (used for include
     headers),
   * used for building the application with qmake instead of CMake
+
 * use the same Qt version for building the example application, as was used
   for building PySide, this is to ensure binary compatibility between the
   newly generated bindings libraries, the PySide libraries and the
@@ -40,20 +45,24 @@ consideration:
 
 For Windows you will also need:
 * a Visual Studio environment to be active in your terminal
+
 * Correct visual studio architecture chosen (32 vs 64 bit)
+
 * Make sure that your Qt + Python + PySide package + app build configuration
   is the same (all Release, which is more likely, or all Debug).
+
 * Make sure that your Qt + Python + PySide package + app are built with the
   same version of MSVC, to avoid mixing of C++ runtime libraries.
   In principle this means that if you use the python.org provided Python
   interpreters, you need to use MSVC2015 for Python 3 projects.
 
-Both build options will use the `pyside_config.py` file to configure the project
-using the current PySide/Shiboken installation (for qmake via pyside.pri,
-and for CMake via the project CMakeLists.txt).
+Both build options will use the ``pyside_config.py`` file to configure the project
+using the current PySide/Shiboken installation (for qmake via ``pyside.pri``,
+and for CMake via the project ``CMakeLists.txt``).
 
 
-### Using CMake
+Using CMake
++++++++++++
 
 To build this example with CMake you will need a recent version of CMake (3.1+).
 
@@ -61,61 +70,69 @@ You can build this example by executing the following commands
 (slightly adapted to your file system layout) in a terminal:
 
 macOS/Linux:
-```bash
-cd ~/pyside-setup/examples/scriptableapplication
-```
+
+.. code-block:: bash
+
+    cd ~/pyside-setup/examples/scriptableapplication
 
 On Windows:
-```bash
-cd C:\pyside-setup\examples\scriptableapplication
-```
 
-```bash
-mkdir build
-cd build
-cmake -H.. -B. -G Ninja -DCMAKE_BUILD_TYPE=Release
-ninja
-./scriptableapplication
-```
+.. code-block:: bash
+
+    cd C:\pyside-setup\examples\scriptableapplication
 
-### Using QMake
 
-The file `scriptableapplication.pro` is the project file associated
+.. code-block:: bash
+
+    mkdir build
+    cd build
+    cmake -H.. -B. -G Ninja -DCMAKE_BUILD_TYPE=Release
+    ninja
+    ./scriptableapplication
+
+Using QMake
++++++++++++
+
+The file ``scriptableapplication.pro`` is the project file associated
 to the example when using qmake.
 
 You can build this example by executing:
-```bash
-mkdir build
-cd build
-qmake ..
-make # or nmake / jom for Windows
-```
 
-#### Windows troubleshooting
+.. code-block:: bash
+
+    mkdir build
+    cd build
+    qmake ..
+    make # or nmake / jom for Windows
+
 
-Using **qmake** should work out of the box, there was a known issue
+Windows troubleshooting
+***********************
+
+Using ``qmake`` should work out of the box, there was a known issue
 with directories and white spaces that is solved by using the
 "~1" character, so the path will change from:
-c:\Program Files\Python34\libs
+``c:\Program Files\Python34\libs``
 to
-c:\Progra~1\Python34\libs
+``c:\Progra~1\Python34\libs``
 this will avoid the issues when the Makefiles are generated.
 
-It is possible when using **cmake** to pick up the wrong compiler
+It is possible when using ``CMake`` to pick up the wrong compiler
 for a different architecture, but it can be addressed explicitly
 using the -G option:
 
-```bash
-cmake -H.. -B. -G "Visual Studio 14 Win64" -DCMAKE_BUILD_TYPE=Release
-```
+.. code-block:: bash
+
+    cmake -H.. -B. -G "Visual Studio 14 Win64" -DCMAKE_BUILD_TYPE=Release
+
+
+If the ``-G "Visual Studio 14 Win64"`` option is used, a ``sln`` file
+will be generated, and can be used with ``MSBuild``
+instead of ``nmake/jom``.
 
-If the `-G "Visual Studio 14 Win64"` option is used, a `sln` file
-will be generated, and can be used with `MSBuild`
-instead of `nmake/jom`.
+.. code-block:: bash
 
-```bash
-MSBuild scriptableapplication.sln "/p:Configuration=Release"
-```
+    MSBuild scriptableapplication.sln "/p:Configuration=Release"
 
 Note that using the "NMake Makefiles JOM" generator is preferred to
 the MSBuild one, because in the latter case the executable is placed
@@ -124,7 +141,8 @@ dlls (shiboken, pyside). This leads to execution problems if the
 application is started within the Release subdirectory and not the
 one containing the dependencies.
 
-## Virtualenv Support
+Virtualenv Support
+******************
 
 If the application is started from a terminal with an activated python
 virtual environment, that environment's packages will be used for the
@@ -133,15 +151,17 @@ In this case, make sure that the application was built while the
 `virtualenv` was active, so that the build system picks up the correct
 python shared library and PySide package.
 
-## Linux Shared Libraries Notes
+Linux Shared Libraries Notes
+****************************
 
 For this example's purpose, we link against the absolute paths of the
-shared libraries (`libshiboken` and `libpyside`) because the
+shared libraries (``libshiboken`` and ``libpyside``) because the
 installation of the modules is being done via wheels, and there is
 no clean solution to include symbolic links in the package
 (so that regular -lshiboken works).
 
-## Windows Notes
+Windows Notes
+*************
 
 The build config of the application (Debug or Release) should match
 the PySide6 build config, otherwise the application will not properly
@@ -149,17 +169,17 @@ work.
 
 In practice this means the only supported configurations are:
 
-1. release config build of the application +
-   PySide `setup.py` without `--debug` flag + `python.exe` for the
-   PySide build process + `python36.dll` for the linked in shared
+#. release config build of the application +
+   PySide ``setup.py`` without ``--debug`` flag + ``python.exe`` for the
+   PySide build process + ``python36.dll`` for the linked in shared
    library + release build of Qt.
-2. debug config build of the application +
-   PySide `setup.py` **with** `--debug` flag + `python_d.exe` for the
-   PySide build process + `python36_d.dll` for the linked in shared
+#. debug config build of the application +
+   PySide ``setup.py`` *with* ``--debug`` flag + ``python_d.exe`` for the
+   PySide build process + ``python36_d.dll`` for the linked in shared
    library + debug build of Qt.
 
 This is necessary because all the shared libraries in question have to
-link to the same C++ runtime library (`msvcrt.dll` or `msvcrtd.dll`).
+link to the same C++ runtime library (``msvcrt.dll`` or ``msvcrtd.dll``).
 To make the example as self-contained as possible, the shared libraries
-in use (`pyside6.dll`, `shiboken6.dll`) are hard-linked into the build
+in use (``pyside6.dll``, ``shiboken6.dll``) are hard-linked into the build
 folder of the application.