diff options
| -rw-r--r-- | examples/quickcontrols2/gallery/doc/gallery.rst | 7 | ||||
| -rw-r--r-- | examples/widgets/tetrix/doc/tetrix-screenshot.png | bin | 0 -> 5396 bytes | |||
| -rw-r--r-- | examples/widgets/tetrix/doc/tetrix.rst | 38 | ||||
| -rw-r--r-- | tools/example_gallery/main.py | 105 |
4 files changed, 118 insertions, 32 deletions
diff --git a/examples/quickcontrols2/gallery/doc/gallery.rst b/examples/quickcontrols2/gallery/doc/gallery.rst new file mode 100644 index 000000000..29cd49f14 --- /dev/null +++ b/examples/quickcontrols2/gallery/doc/gallery.rst @@ -0,0 +1,7 @@ +Qt Quick Controls 2 - Gallery +============================= + +The gallery example is a simple application with a drawer menu that contains +all the Qt Quick Controls 2. Each menu item opens a page that shows the +graphical appearance of a control, allows you to interact with the control, and +explains in which circumstances it is handy to use this control. diff --git a/examples/widgets/tetrix/doc/tetrix-screenshot.png b/examples/widgets/tetrix/doc/tetrix-screenshot.png Binary files differnew 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. diff --git a/tools/example_gallery/main.py b/tools/example_gallery/main.py index 4a20760b7..f1a9c4c5f 100644 --- a/tools/example_gallery/main.py +++ b/tools/example_gallery/main.py @@ -51,6 +51,7 @@ since there is no special requirements. from argparse import ArgumentParser, RawTextHelpFormatter import json import math +import shutil from pathlib import Path from textwrap import dedent @@ -148,6 +149,44 @@ def remove_licenses(s): return "\n".join(new_s) +def get_code_tabs(files, project_file): + content = "\n" + + for i, project_file in enumerate(files): + pfile = Path(project_file) + if pfile.suffix in (".png", ".pyc"): + continue + + if i == 0: + content += ".. tabs::\n\n" + + suffix = get_lexer(pfile.suffix) + content += add_indent(f".. code-tab:: {suffix} {project_file}", 1) + content += "\n" + + _path = f_path.resolve().parents[0] / project_file + _file_content = "" + with open(_path, "r") as _f: + _file_content = remove_licenses(_f.read()) + + content += add_indent(_file_content, 2) + content += "\n\n" + return content + + +def get_header_title(f_path): + _title = f_path.stem + url_name = "/".join(f_path.parts[f_path.parts.index("examples")+1:-1]) + url = f"{BASE_URL}/{url_name}" + return ( + "..\n This file was auto-generated by the 'examples_gallery' " + "script.\n Any change will be lost!\n\n" + f"{_title}\n" + f"{'=' * len(_title)}\n\n" + f"(You can also check this code `in the repository <{url}>`_)\n\n" + ) + + if __name__ == "__main__": # Only examples with a '.pyproject' file will be listed. DIR = Path(__file__).parent @@ -172,7 +211,7 @@ if __name__ == "__main__": if str(f_path).endswith("examples.pyproject"): continue - parts = f_path.parts[len(EXAMPLES_DIR.parts) : -1] + parts = f_path.parts[len(EXAMPLES_DIR.parts):-1] module_name = parts[0] example_name = parts[-1] @@ -181,6 +220,12 @@ if __name__ == "__main__": rst_file = f"example_{module_name}_{extra_names}_{example_name}.rst" + # Check for a 'doc' directory inside the example + has_doc = False + original_doc_dir = Path(f_path.parent / "doc") + if original_doc_dir.is_dir(): + has_doc = True + if module_name not in examples: examples[module_name] = [] @@ -191,6 +236,7 @@ if __name__ == "__main__": "extra": extra_names, "rst": rst_file, "abs_path": str(f_path), + "has_doc": has_doc, } ) @@ -199,38 +245,33 @@ if __name__ == "__main__": pyproject = json.load(pyf) if pyproject: - with open(f"{EXAMPLES_DOC}/{rst_file}", "w") as out_f: - _title = f_path.stem - _title_line = "=" * len(_title) - url_name = "/".join(f_path.parts[f_path.parts.index("examples") + 1 : -1]) - url = f"{BASE_URL}/{url_name}" - content_f = ( - "..\n This file was auto-generated by the 'examples_gallery' " - "script.\n Any change will be lost!\n\n" - f"{_title}\n" - f"{_title_line}\n\n" - f"(You can also check this code `in the repository <{url}>`_)\n\n" - ) - for i, project_file in enumerate(pyproject["files"]): - pfile = Path(project_file) - if pfile.suffix in (".png", ".pyc"): - continue - - if i == 0: - content_f += ".. tabs::\n\n" - - lexer = get_lexer(pfile.suffix) - content_f += add_indent(f".. code-tab:: {lexer} {project_file}", 1) - content_f += "\n" - - _path = f_path.resolve().parents[0] / project_file - _content = "" - with open(_path, "r") as _f: - _content = remove_licenses(_f.read()) - - content_f += add_indent(_content, 2) - content_f += "\n\n" + rst_file_full = Path(EXAMPLES_DOC) / rst_file + + with open(rst_file_full, "w") as out_f: + if has_doc: + doc_path = Path(f_path.parent) / "doc" + doc_rst = doc_path / f"{example_name}.rst" + + with open(doc_rst) as doc_f: + content_f = doc_f.read() + + # Copy other files in the 'doc' directory, but + # excluding the main '.rst' file and all the + # directories. + for _f in doc_path.glob("*"): + if _f == doc_rst or _f.is_dir(): + continue + src = _f + dst = Path(EXAMPLES_DOC) / _f.name + + resource_written = shutil.copy(src, dst) + if not opt_quiet: + print("Written resource:", resource_written) + else: + content_f = get_header_title(f_path) + content_f += get_code_tabs(pyproject["files"], out_f) out_f.write(content_f) + if not opt_quiet: print(f"Written: {EXAMPLES_DOC}/{rst_file}") else: |
