From 53f9ee38f1f37a8a98373f7a21814159dccdbed6 Mon Sep 17 00:00:00 2001 From: Cristian Maureira-Fredes Date: Wed, 17 Feb 2021 22:18:49 +0100 Subject: 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 (cherry picked from commit a7c7c729a388b0a4e0e104fac1130feb6e03151b) Reviewed-by: Qt Cherry-pick Bot --- requirements.txt | 1 + sources/pyside6/doc/conf.py.in | 3 ++- tools/example_gallery/main.py | 58 ++++++++++++++++++++++++++++++++---------- 3 files changed, 47 insertions(+), 15 deletions(-) diff --git a/requirements.txt b/requirements.txt index dd4b6cc8e..2f60cb9ee 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,6 @@ setuptools sphinx +sphinx-tabs six wheel>=0.35 PyOpenGL diff --git a/sources/pyside6/doc/conf.py.in b/sources/pyside6/doc/conf.py.in index 5a034f465..45df12344 100644 --- a/sources/pyside6/doc/conf.py.in +++ b/sources/pyside6/doc/conf.py.in @@ -29,7 +29,8 @@ if @HAS_WEBENGINE_WIDGETS@: extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.ifconfig', 'sphinx.ext.coverage', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.graphviz', 'inheritance_diagram', 'pysideinclude', -'sphinx.ext.viewcode'] +'sphinx.ext.viewcode', +'sphinx_tabs.tabs'] output_format='@DOC_OUTPUT_FORMAT@' 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)}\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"""\ {get_colgroup(columns, indent=3)} @@ -116,7 +131,8 @@ def get_module_gallery(examples): gallery += f'{ind(2)}\n' gallery += f"{ind(1)}\n" - gallery += dedent("""\ + gallery += dedent( + """\
""" ) @@ -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 -- cgit v1.2.3