doc: use 'doc' directory for examples gallery

The initial patch that generates a gallery based on the examples in the
respository, was limited to only showing the content of the files
in each '.pyproject' file.

That approach didn't allow to describe each example, nor add
complementary images, like screenshots to each example page.

This patch introduces the option to consider everything inside a 'doc/'
directory on the example directory. The files that are copied over are
not directory, but only files, for images to be the main focus.

For example, currently the Tetrix case contained the following files:

    $ ls examples/widgets/tetrix/
    tetrix.py
    tetrix.pyproject

On this patch you can see that now there is a doc directory with the
following content:

    $ ls examples/widgets/tetrix/doc
    tetrix-screenshot.png
    tetrix.rst

The example page that will be generated for this case will contain the
content of the 'doc/tetrix.rst' file, plus the content of all the
project files at the end.

The 'doc/tetrix.rst' file contains a reference to the
'tetrix-screenshot.png' image, so that file will be copied over too.

Task-number: PYSIDE-1112
Pick-to: 6.0
Change-Id: I2d11833c461d8073d2d2888576d876d3f834103a
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>

2 files changed, 38 insertions, 0 deletions

diff --git a/examples/widgets/tetrix/doc/tetrix-screenshot.png b/examples/widgets/tetrix/doc/tetrix-screenshot.png
new file mode 100644
index 000000000..2c3dade39
--- /dev/null
+++ b/examples/widgets/tetrix/doc/tetrix-screenshot.png
diff --git a/examples/widgets/tetrix/doc/tetrix.rst b/examples/widgets/tetrix/doc/tetrix.rst
new file mode 100644
index 000000000..0749de9de
--- /dev/null
+++ b/examples/widgets/tetrix/doc/tetrix.rst
@@ -0,0 +1,38 @@
+Tetrix
+======
+
+The Tetrix example is a Qt version of the classic Tetrix game.
+
+.. image:: tetrix-screenshot.png
+  :width: 400
+  :alt: Tetrix main window
+
+The object of the game is to stack pieces dropped from the top of the playing
+area so that they fill entire rows at the bottom of the playing area.
+
+When a row is filled, all the blocks on that row are removed, the player earns
+a number of points, and the pieces above are moved down to occupy that row. If
+more than one row is filled, the blocks on each row are removed, and the player
+earns extra points.
+
+The **Left** cursor key moves the current piece one space to the left, the
+**Right** cursor key moves it one space to the right, the **Up** cursor key
+rotates the piece counter-clockwise by 90 degrees, and the **Down** cursor key
+rotates the piece clockwise by 90 degrees.
+
+To avoid waiting for a piece to fall to the bottom of the board, press **D** to
+immediately move the piece down by one row, or press the **Space** key to drop
+it as close to the bottom of the board as possible.
+
+This example shows how a simple game can be created using only three classes:
+
+* The ``TetrixWindow`` class is used to display the player's score, number of
+  lives, and information about the next piece to appear.
+* The ``TetrixBoard`` class contains the game logic, handles keyboard input, and
+  displays the pieces on the playing area.
+* The ``TetrixPiece`` class contains information about each piece.
+
+In this approach, the ``TetrixBoard`` class is the most complex class, since it
+handles the game logic and rendering. One benefit of this is that the
+``TetrixWindow`` and ``TetrixPiece`` classes are very simple and contain only a
+minimum of code.