From 885835442950ed6b8fefcacb68098da83a82a859 Mon Sep 17 00:00:00 2001 From: Joey Vagedes Date: Wed, 30 Aug 2023 10:11:16 -0700 Subject: [PATCH 1/5] mkdocs: General DocSite improvements. - Changes the theme to material instead of readthedocs as there are no longer any plans to post this to readthedocs. - Utilizes new features in mkdocs-awesome-pages to allow for a hierarchical sidebar for the API references rather than a flattened list of API references. --- docs/user/gen_api.py | 9 ++++++++- edk2toollib/database/edk2_db.py | 35 ++++++++++++++++++++++++++++++--- mkdocs.yml | 14 ++++++++++--- 3 files changed, 51 insertions(+), 7 deletions(-) diff --git a/docs/user/gen_api.py b/docs/user/gen_api.py index c601127f..12bf836f 100644 --- a/docs/user/gen_api.py +++ b/docs/user/gen_api.py @@ -6,13 +6,15 @@ # SPDX-License-Identifier: BSD-2-Clause-Patent ## """Python script used to automatically generate API Reference documentation. + Used in conjunction with mkdocs to generate static markdown files for each file inside the edk2toollib package for ReadTheDocs hosting. """ -import mkdocs_gen_files import glob import os +import mkdocs_gen_files + def main(): """Entry into script that is executed.""" @@ -52,5 +54,10 @@ def main(): edit_path = os.path.join('..', 'edk2toollib', edit_path) mkdocs_gen_files.set_edit_path(filename, edit_path) + with mkdocs_gen_files.open("api/.pages", "w") as f: + print("title: API Reference", file=f) + print("nav:", file=f) + print(" - ...", file=f) + main() diff --git a/edk2toollib/database/edk2_db.py b/edk2toollib/database/edk2_db.py index 00d3560e..9142ee00 100644 --- a/edk2toollib/database/edk2_db.py +++ b/edk2toollib/database/edk2_db.py @@ -14,7 +14,6 @@ from edk2toollib.database.tables import EnvironmentTable from edk2toollib.database.tables.base_table import TableGenerator -from edk2toollib.uefi.edk2.path_utilities import Edk2Path CREATE_JUNCTION_TABLE = """ CREATE TABLE IF NOT EXISTS junction ( @@ -58,9 +57,39 @@ class Edk2DB: db.register(Parser1(), Parser2(), Parser3()) db.parse() - db.connection.execute("SELECT * FROM ?", table) + # Run using Memory storage + from edk2toollib.database.parsers import * + with Edk2DB(Edk2DB.MEM_RW, pathobj=edk2path) as db: + db.register(Parser1(), Parser2(), Parser3()) + db.parse() + + # Run some parsers in clear mode and some in append mode + from edk2toollib.database.parsers import * + with Edk2DB(Edk2DB.MEM_RW, pathobj=edk2path) as db: + db.register(Parser1()) + db.parse() + db.clear_parsers() + + db.register(Parser2(), Parser3()) + for env in env_list: + db.parse(env=env, append=True) + + # Run Queries on specific tables or on the database + from edk2toollib.database.queries import * + with Edk2DB(Edk2DB.FILE_RW, pathobj=edk2path, db_path=Path("path/to/db.db")) as db: + # Run a tinydb Query + # https://tinydb.readthedocs.io/en/latest/usage.html#queries + query_results = db.table("TABLENAME").search(Query().table_field == "value") + + # Run an advanced query + query_results = db.search(AdvancedQuerySubclass(config1 = "x", config2 = "y")) + ``` """ - def __init__(self: 'Edk2DB', db_path: str, pathobj: Edk2Path = None, **kwargs: dict[str,Any]) -> 'Edk2DB': + FILE_RW = 1 # Mode: File storage, Read & Write + FILE_RO = 2 # Mode: File storage, Read Only + MEM_RW = 3 # Mode: Memory storage, Read & Write + + def __init__(self, mode: int, **kwargs: dict[str,Any]): """Initializes the database. Args: diff --git a/mkdocs.yml b/mkdocs.yml index fe8f1fb1..7c71b047 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,7 +4,16 @@ copyright: Copyright (c) Microsoft. All rights reserved site_description: edk2toollib package documentation theme: - name: readthedocs + name: material + palette: + - scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to light mode docs_dir: docs/user @@ -71,5 +80,4 @@ nav: - Get Host Info: features/utility_functions.GetHostInfo.md - Windows Firmware Policy: features/windows_firmware_policy.md - Build Objects: features/build_objects.md - - API Reference: - - ... | flat | api/**/*.md + - ... From 1df859b91f4cc1edf4b37b513fad79700df89bc2 Mon Sep 17 00:00:00 2001 From: Joey Vagedes Date: Wed, 30 Aug 2023 11:12:36 -0700 Subject: [PATCH 2/5] update --- docs/user/features/.pages | 1 + docs/user/gen_api.py | 2 -- docs/user/index.md | 5 +++++ mkdocs.yml | 14 ++++++-------- 4 files changed, 12 insertions(+), 10 deletions(-) create mode 100644 docs/user/features/.pages diff --git a/docs/user/features/.pages b/docs/user/features/.pages new file mode 100644 index 00000000..59863e77 --- /dev/null +++ b/docs/user/features/.pages @@ -0,0 +1 @@ +title: Advanced Features diff --git a/docs/user/gen_api.py b/docs/user/gen_api.py index 12bf836f..73dae006 100644 --- a/docs/user/gen_api.py +++ b/docs/user/gen_api.py @@ -56,8 +56,6 @@ def main(): with mkdocs_gen_files.open("api/.pages", "w") as f: print("title: API Reference", file=f) - print("nav:", file=f) - print(" - ...", file=f) main() diff --git a/docs/user/index.md b/docs/user/index.md index 194aa5b9..af2d6bf1 100644 --- a/docs/user/index.md +++ b/docs/user/index.md @@ -1,3 +1,8 @@ +--- +hide: + - navigation + - toc +--- # Our Philosophy Edk2 Pytool Library (edk2toollib) is a Tianocore maintained project consisting diff --git a/mkdocs.yml b/mkdocs.yml index 7c71b047..fed0ece2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,6 +5,9 @@ site_description: edk2toollib package documentation theme: name: material + features: + - navigation.tabs + - navigation.indexes palette: - scheme: default toggle: @@ -73,11 +76,6 @@ watch: - 'edk2toollib/' nav: - - Our Philosophy: index.md - - Advanced Features: - - Edk2 Database: features/edk2_db.md - - ANSI Logging: features/logging.ansi_handler.md - - Get Host Info: features/utility_functions.GetHostInfo.md - - Windows Firmware Policy: features/windows_firmware_policy.md - - Build Objects: features/build_objects.md - - ... + - Home: index.md + - ... | features/**/*.md + - ... | api/**/*.md From 9573883485b6ea53a6b6c3bea539d81b81fae26a Mon Sep 17 00:00:00 2001 From: "Joey Vagedes (from Dev Box)" Date: Thu, 11 Jan 2024 10:15:44 -0800 Subject: [PATCH 3/5] update --- edk2toollib/database/edk2_db.py | 34 +++------------------------------ 1 file changed, 3 insertions(+), 31 deletions(-) diff --git a/edk2toollib/database/edk2_db.py b/edk2toollib/database/edk2_db.py index 9142ee00..4a0c60e7 100644 --- a/edk2toollib/database/edk2_db.py +++ b/edk2toollib/database/edk2_db.py @@ -14,6 +14,7 @@ from edk2toollib.database.tables import EnvironmentTable from edk2toollib.database.tables.base_table import TableGenerator +from edk2toollib.uefi.edk2.path_utilities import Edk2Path CREATE_JUNCTION_TABLE = """ CREATE TABLE IF NOT EXISTS junction ( @@ -56,40 +57,11 @@ class Edk2DB: with Edk2DB(Path("path/to/db.db"), edk2path) as db: db.register(Parser1(), Parser2(), Parser3()) db.parse() - - # Run using Memory storage - from edk2toollib.database.parsers import * - with Edk2DB(Edk2DB.MEM_RW, pathobj=edk2path) as db: - db.register(Parser1(), Parser2(), Parser3()) - db.parse() - - # Run some parsers in clear mode and some in append mode - from edk2toollib.database.parsers import * - with Edk2DB(Edk2DB.MEM_RW, pathobj=edk2path) as db: - db.register(Parser1()) - db.parse() - db.clear_parsers() - - db.register(Parser2(), Parser3()) - for env in env_list: - db.parse(env=env, append=True) - - # Run Queries on specific tables or on the database - from edk2toollib.database.queries import * - with Edk2DB(Edk2DB.FILE_RW, pathobj=edk2path, db_path=Path("path/to/db.db")) as db: - # Run a tinydb Query - # https://tinydb.readthedocs.io/en/latest/usage.html#queries - query_results = db.table("TABLENAME").search(Query().table_field == "value") - - # Run an advanced query - query_results = db.search(AdvancedQuerySubclass(config1 = "x", config2 = "y")) + db.connection.execute("SELECT * FROM ?", table) ``` """ - FILE_RW = 1 # Mode: File storage, Read & Write - FILE_RO = 2 # Mode: File storage, Read Only - MEM_RW = 3 # Mode: Memory storage, Read & Write - def __init__(self, mode: int, **kwargs: dict[str,Any]): + def __init__(self: 'Edk2DB', db_path: str, pathobj: Edk2Path = None, **kwargs: dict[str,Any]) -> 'Edk2DB': """Initializes the database. Args: From 581ba429253434b7ac4b383cfe8f8c062c6e5c1f Mon Sep 17 00:00:00 2001 From: "Joey Vagedes (from Dev Box)" Date: Thu, 11 Jan 2024 10:18:20 -0800 Subject: [PATCH 4/5] update --- edk2toollib/database/edk2_db.py | 1 - 1 file changed, 1 deletion(-) diff --git a/edk2toollib/database/edk2_db.py b/edk2toollib/database/edk2_db.py index 4a0c60e7..bfd51bf3 100644 --- a/edk2toollib/database/edk2_db.py +++ b/edk2toollib/database/edk2_db.py @@ -60,7 +60,6 @@ class Edk2DB: db.connection.execute("SELECT * FROM ?", table) ``` """ - def __init__(self: 'Edk2DB', db_path: str, pathobj: Edk2Path = None, **kwargs: dict[str,Any]) -> 'Edk2DB': """Initializes the database. From 8d39bade1aa32de82740a6ab1942dacd25d424a2 Mon Sep 17 00:00:00 2001 From: "Joey Vagedes (from Dev Box)" Date: Thu, 11 Jan 2024 10:33:25 -0800 Subject: [PATCH 5/5] update --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index fed0ece2..9a433d8e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -53,7 +53,7 @@ markdown_extensions: - pymdownx.critic - pymdownx.details - pymdownx.emoji: - emoji_index: !!python/name:materialx.emoji.twemoji + emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg - pymdownx.inlinehilite - pymdownx.magiclink