mkdocs: General DocSite improvements. (#400)

Associated with #392, but will not close until also completed in edk2-pytool-extensions.

- 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.

- Adds light / dark mode to the docs

- Adds navigation tabs in the header for the main li

docs/user/features/.pages

@@ -0,0 +1 @@
+title: Advanced Features

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,8 @@ 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)
+
 
 main()

docs/user/index.md

@@ -1,3 +1,8 @@
+---
+hide:
+  - navigation
+  - toc
+---
 # Our Philosophy
 
 Edk2 Pytool Library (edk2toollib) is a Tianocore maintained project consisting

edk2toollib/database/edk2_db.py

@@ -57,8 +57,8 @@ class Edk2DB:
         with Edk2DB(Path("path/to/db.db"), edk2path) as db:
             db.register(Parser1(), Parser2(), Parser3())
             db.parse()
-
             db.connection.execute("SELECT * FROM ?", table)
+        ```
     """
     def __init__(self: 'Edk2DB', db_path: str, pathobj: Edk2Path = None, **kwargs: dict[str,Any]) -> 'Edk2DB':
         """Initializes the database.

mkdocs.yml

@@ -4,7 +4,19 @@ copyright: Copyright (c) Microsoft.  All rights reserved
 site_description: edk2toollib package documentation
 
 theme:
-  name: readthedocs
+  name: material
+  features:
+    - navigation.tabs
+    - navigation.indexes
+  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
 
@@ -41,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
@@ -64,12 +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
-  - API Reference:
-    - ... | flat | api/**/*.md
+  - Home: index.md
+  - ... | features/**/*.md
+  - ... | api/**/*.md