diff options
author | Cristian Maureira-Fredes <Cristian.Maureira-Fredes@qt.io> | 2021-02-17 22:18:49 +0100 |
---|---|---|
committer | Qt Cherry-pick Bot <cherrypick_bot@qt-project.org> | 2021-03-03 13:14:27 +0000 |
commit | 53f9ee38f1f37a8a98373f7a21814159dccdbed6 (patch) | |
tree | c50d172713c23f1c1bf33fa338d0519e9f7b835e /tools | |
parent | 4ab34c2fe7d7acfea6a7d5ea4e905e0e83651710 (diff) |
doc: example gallery show code in tabs
Before this patch, the auto-generated documentation page
had all the files from the .pyproject listed one after the other.
This uses a new sphinx extension called sphinx-tabs
https://github.com/executablebooks/sphinx-tabs
which allows us to easily add content in tabs.
Task-number: PYSIDE-1112
Change-Id: Ibd66a8c911f05be13ae2700be6d3e95a2b98b775
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
(cherry picked from commit a7c7c729a388b0a4e0e104fac1130feb6e03151b)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
Diffstat (limited to 'tools')
-rw-r--r-- | tools/example_gallery/main.py | 58 |
1 files changed, 44 insertions, 14 deletions
diff --git a/tools/example_gallery/main.py b/tools/example_gallery/main.py index afacab628..4a20760b7 100644 --- a/tools/example_gallery/main.py +++ b/tools/example_gallery/main.py @@ -38,7 +38,7 @@ ############### -DESCRIPTION = """ +""" This tool reads all the examples from the main repository that have a '.pyproject' file, and generates a special table/gallery in the documentation page. @@ -56,6 +56,14 @@ from textwrap import dedent opt_quiet = False +suffixes = { + ".py": "py", + ".qml": "js", + ".conf": "ini", + ".qrc": "xml", + ".ui": "xml", + ".xbel": "xml", +} def ind(x): @@ -68,6 +76,12 @@ def get_colgroup(columns, indent=2): return f'{ind(indent)}<col style="width: {width_column}%" />\n' * columns +def get_lexer(suffix): + if suffix in suffixes: + return suffixes[suffix] + return "text" + + def add_indent(s, level): new_s = "" for line in s.splitlines(): @@ -84,7 +98,8 @@ def get_module_gallery(examples): information, from one specific module. """ - gallery = dedent(f"""\ + gallery = dedent( + f"""\ <table class="special"> <colgroup> {get_colgroup(columns, indent=3)} @@ -116,7 +131,8 @@ def get_module_gallery(examples): gallery += f'{ind(2)}<td style="display: none;"></td>\n' gallery += f"{ind(1)}</tr>\n" - gallery += dedent("""\ + gallery += dedent( + """\ </table> """ ) @@ -137,13 +153,12 @@ if __name__ == "__main__": DIR = Path(__file__).parent EXAMPLES_DOC = f"{DIR}/../../sources/pyside6/doc/examples" EXAMPLES_DIR = Path(f"{DIR}/../../examples/") + BASE_URL = "https://code.qt.io/cgit/pyside/pyside-setup.git/tree/examples" columns = 5 gallery = "" - parser = ArgumentParser(description=DESCRIPTION, - formatter_class=RawTextHelpFormatter) - parser.add_argument('--quiet', '-q', action='store_true', - help='Quiet') + parser = ArgumentParser(description=__doc__, formatter_class=RawTextHelpFormatter) + parser.add_argument("--quiet", "-q", action="store_true", help="Quiet") options = parser.parse_args() opt_quiet = options.quiet @@ -185,22 +200,35 @@ if __name__ == "__main__": 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 project_file in pyproject["files"]: - if project_file.split(".")[-1] in ("png", "pyc"): + for i, project_file in enumerate(pyproject["files"]): + pfile = Path(project_file) + if pfile.suffix in (".png", ".pyc"): continue - length = len(project_file) - content_f += f"{project_file}\n{'=' * length}\n\n::\n\n" + + 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, 1) + content_f += add_indent(_content, 2) content_f += "\n\n" out_f.write(content_f) if not opt_quiet: @@ -209,7 +237,8 @@ if __name__ == "__main__": if not opt_quiet: print("Empty '.pyproject' file, skipping") - base_content = dedent("""\ + base_content = dedent( + """\ .. This file was auto-generated from the 'pyside-setup/tools/example_gallery' All editions in this file will be lost. @@ -243,7 +272,8 @@ if __name__ == "__main__": # for them will be able to, since they are indexed. # Notice that :hidden: will not add the list of files by the end of the # main examples HTML page. - footer_index = dedent("""\ + footer_index = dedent( + """\ .. toctree:: :hidden: :maxdepth: 1 |