Merge pull request #2 from docsforadobe/change/common-config

Update repo to use common org-wide components

Author: zlovatt

.github/workflows/ci.yml

@@ -22,6 +22,7 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
+
       - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
 
       - uses: actions/cache@v4
@@ -30,9 +31,8 @@ jobs:
           path: .cache
           restore-keys: |
             mkdocs-material-
-      - run: >
-          pip install
-          mkdocs-material
-          mkdocs-git-revision-date-localized-plugin
-          mkdocs-print-site-plugin
+
+      - name: Install Python dependencies
+        uses: py-actions/py-dependency-install@v4
+
       - run: mkdocs gh-deploy --force

.gitignore

@@ -2,5 +2,6 @@
 *.sublime-workspace
 .DS_Store
 .vscode/
+__pycache__/
 site/
 venv/

docs/_global/.gitignore

@@ -0,0 +1,7 @@
+*.sublime-project
+*.sublime-workspace
+.DS_Store
+.vscode/
+__pycache__/
+site/
+venv/

docs/_global/css/global-syntax-highlight.css

@@ -0,0 +1,43 @@
+/* Set light & dark mode syntax highlight */
+
+@media screen {
+	/* Light mode */
+	[data-md-color-scheme="default"] {
+		--md-code-fg-color: #36464e;
+		--md-code-bg-color: #f5f5f5;
+		--md-code-hl-color: #4287ff;
+
+		--md-code-hl-constant-color: #6e59d9;
+		--md-code-hl-function-color: #a846b9;
+		--md-code-hl-keyword-color: #3f6ec6;
+		--md-code-hl-number-color: #d52a2a;
+		--md-code-hl-special-color: #db1457;
+		--md-code-hl-string-color: #1c7d4d;
+		--md-code-hl-comment-color: var(--md-default-fg-color--light);
+		--md-code-hl-generic-color: var(--md-default-fg-color--light);
+		--md-code-hl-name-color: var(--md-code-fg-color);
+		--md-code-hl-operator-color: var(--md-default-fg-color--light);
+		--md-code-hl-punctuation-color: var(--md-default-fg-color--light);
+		--md-code-hl-variable-color: var(--md-default-fg-color--light);
+	}
+
+	/* Dark mode */
+	[data-md-color-scheme="slate"] {
+		--md-code-bg-color: #272a35;
+		--md-code-fg-color: #d5d8e2d1;
+		--md-code-hl-color: #2977ff;
+
+		--md-code-hl-constant-color: #9383e2;
+		--md-code-hl-function-color: #c973d9;
+		--md-code-hl-keyword-color: #6791e0;
+		--md-code-hl-number-color: #e6695b;
+		--md-code-hl-special-color: #f06090;
+		--md-code-hl-string-color: #2fb170;
+		--md-code-hl-comment-color: var(--md-default-fg-color--light);
+		--md-code-hl-generic-color: var(--md-default-fg-color--light);
+		--md-code-hl-name-color: var(--md-code-fg-color);
+		--md-code-hl-operator-color: var(--md-default-fg-color--light);
+		--md-code-hl-punctuation-color: var(--md-default-fg-color--light);
+		--md-code-hl-variable-color: var(--md-default-fg-color--light);
+	}
+}

docs/_global/css/global.css

@@ -0,0 +1,4 @@
+/* Fix issue with 'code' text in tables wrapping to multiple lines */
+td code {
+    white-space: nowrap;
+}

docs/_global/hooks/merge_inherited_config.py

@@ -0,0 +1,119 @@
+# Handles merging mkdocs config in a way the native inheritance feature doesn't quite cover
+#
+# This relies on a key in "extra.overrides"
+# Valid keys are `custom_dir: str` and `hooks: [-path/to.py, -path/to.py]`, e.g.
+#
+# ```yml
+# extra:
+#     overrides:
+#         custom_dir: overrides
+#         extra_css:
+#             - docs/_global/css/global.css
+#             - docs/_global/css/global-syntax-highlight.css
+#         extra_javascript:
+#             - docs/_global/js/global.js
+#         hooks:
+#             - hooks/local_override.py
+#             - hooks/local_override2.py
+#         not_in_nav:
+#             - gitignore_style/path/to/exclude
+#         theme_features:
+#             - theme.feature1
+#             - theme.feature2
+# ```
+
+import os
+
+from pathspec.gitignore import GitIgnoreSpec
+
+import mkdocs
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.config.config_options import (File, FilesystemObject, Hooks, ListOfItems, PathSpec)
+from mkdocs.structure.files import (File as FileStructure, Files)
+
+# Load any local files into mkdocs
+def append_local_files(files: Files, config: MkDocsConfig, local_files: list[str]):
+    for local_file_path in local_files:
+        local_file = FileStructure(
+            path= local_file_path,
+            src_dir=config["docs_dir"] + "/../",
+            dest_dir=config["site_dir"],
+            use_directory_urls=False,
+        )
+
+        files.append(local_file)
+
+# Load any override hooks
+def merge_local_hooks(config: MkDocsConfig, hooks: list[str]):
+    try:
+        paths = ListOfItems(File(exists=True)).validate(hooks)
+    except Exception as e:
+        raise e
+
+    for name, path in zip(hooks, paths):
+        config.plugins[name] = Hooks._load_hook(mkdocs, name, path)
+
+# Handle multiple "not in nav" entries
+# These are of a pathspec.gitignore.GitIgnoreSpec format and need to be converted to a multiline string
+def merge_local_not_in_nav(config: MkDocsConfig, not_in_nav: list[GitIgnoreSpec]):
+    nav_str = "\n".join(not_in_nav)
+    config["not_in_nav"] += PathSpec().run_validation(nav_str)
+
+# Add additional theme_override folder
+def merge_local_theme_override(config: MkDocsConfig, custom_dir: str):
+    try:
+        local_override_path = FilesystemObject(exists=True).validate(custom_dir)
+    except Exception as e:
+        raise e
+
+    config.theme.dirs.insert(1, local_override_path)
+
+# Load any override theme features
+def merge_local_theme_features(config: MkDocsConfig, theme_features: list[str]):
+    for local_feature in theme_features:
+        config.theme["features"].append(local_feature)
+
+
+
+##### MkDocs Event Hooks
+
+def on_files(files: Files, config: MkDocsConfig):
+    if "overrides" in config.extra:
+        extra_overrides = config.extra["overrides"]
+
+        if "extra_css" in extra_overrides:
+            extra_css = extra_overrides["extra_css"]
+            append_local_files(files, config, extra_css)
+
+        if "extra_javascript" in extra_overrides:
+            extra_javascript = extra_overrides["extra_javascript"]
+            append_local_files(files, config, extra_javascript)
+
+def on_config(config: MkDocsConfig):
+    if "overrides" in config.extra:
+        extra_overrides = config.extra["overrides"]
+
+        # Keep Hooks first
+        if "hooks" in extra_overrides:
+            hooks = extra_overrides["hooks"]
+            merge_local_hooks(config, hooks)
+
+        if "custom_dir" in extra_overrides:
+            custom_dir = extra_overrides["custom_dir"]
+            merge_local_theme_override(config, custom_dir)
+
+        if "extra_css" in extra_overrides:
+            extra_css = extra_overrides["extra_css"]
+            config.extra_css.extend(extra_css)
+
+        if "extra_javascript" in extra_overrides:
+            extra_javascript = extra_overrides["extra_javascript"]
+            config.extra_javascript.extend(extra_javascript)
+
+        if "not_in_nav" in extra_overrides:
+            not_in_nav = extra_overrides["not_in_nav"]
+            merge_local_not_in_nav(config, not_in_nav)
+
+        if "theme_features" in extra_overrides:
+            theme_features = extra_overrides["theme_features"]
+            merge_local_theme_features(config, theme_features)

docs/_global/js/global.js

@@ -0,0 +1,74 @@
+# Shared config for all repos
+copyright: All content is copyright Adobe Systems Incorporated.
+
+extra:
+    homepage: https://docsforadobe.dev
+
+    # Using overrides here as we can't inherit "extra_css"
+    overrides:
+        extra_css:
+            - docs/_global/css/global.css
+            - docs/_global/css/global-syntax-highlight.css
+        extra_javascript:
+            - docs/_global/js/global.js
+
+hooks:
+    - docs/_global/hooks/merge_inherited_config.py
+
+markdown_extensions:
+    admonition: {}
+    markdown_grid_tables: {}
+    md_in_html: {}
+    pymdownx.details: {}
+    pymdownx.superfences: {}
+    pymdownx.tabbed:
+        alternate_style: true
+    pymdownx.tasklist:
+        custom_checkbox: true
+    toc:
+        title: Page Contents
+        permalink: true
+        toc_depth: 3
+
+not_in_nav: |
+  _global
+
+plugins:
+    git-revision-date-localized: {}
+    search:
+        separator: '[\s\-,\.:!=\[\]()"/]+'
+
+    # Note: print-site must be last!
+    print-site:
+        add_cover_page: true
+        add_print_site_banner: true
+        cover_page_template: "docs/_global/overrides/templates/print_site_cover_page.tpl"
+        print_page_title: "Offline Docs"
+        print_site_banner_template: "docs/_global/overrides/templates/print_site_banner.tpl"
+
+theme:
+    name: material
+    custom_dir: docs/_global/overrides
+    features:
+        - announce.dismiss
+        - content.action.edit
+        - content.action.view
+        - search.highlight
+        - search.suggest
+        - toc.follow
+    palette:
+        # Palette toggle for dark mode
+        - media: "(prefers-color-scheme: dark)"
+          primary: black
+          scheme: slate
+          toggle:
+              icon: material/brightness-4
+              name: Switch to light mode
+
+        # Palette toggle for light mode
+        - media: "(prefers-color-scheme: light)"
+          primary: white
+          scheme: default
+          toggle:
+              icon: material/brightness-7
+              name: Switch to dark mode

docs/_global/mkdocs.yml

@@ -1,7 +1,7 @@
 {% extends "base.html" %}
 
 {% block announce %}
-  Welcome to the new scripting guide!
+  Welcome to the new docsforadobe guide!
 
   This is a work in progress.
 

overrides/404.html renamed to docs/_global/overrides/404.html

@@ -0,0 +1,11 @@
+# docsforadobe.dev MkDocs Config
+
+This repo holds the common components shared between this org's hosted MkDocs documentation projects.
+
+The idea is that this repo will be kept up-to-date with global config, and each child repo will use the provided script to download the latest commit from this repo, and have its "local" MkDocs config point to the downloaded files from this repo.
+
+In all cases, each child repo will be able to *override* config items here as needed.
+
+## Updating This Repo
+
+See [Modifying Common Components](https://docsforadobe.dev/contributing/common-components/modifying-common-components/) in the org contribution guide for info on how this repo works, and best practices for modifying it.

overrides/main.html renamed to docs/_global/overrides/main.html

@@ -0,0 +1,5 @@
+markdown_grid_tables
+mkdocs
+mkdocs-git-revision-date-localized-plugin
+mkdocs-material
+mkdocs-print-site-plugin

overrides/partials/copyright.html renamed to docs/_global/overrides/partials/copyright.html

@@ -0,0 +1,30 @@
+import os
+import shutil
+import tarfile
+import tempfile
+import urllib.request
+
+org_name = "docsforadobe"
+repo_name = "docsforadobe-mkdocs-config"
+destination_dir = "./docs/_global"
+
+def download_github_repo(org_name, repo_name, destination_dir):
+    tar_url = f"https://api.github.com/repos/{org_name}/{repo_name}/tarball/main"
+
+    response = urllib.request.urlopen(tar_url)
+
+    if (response):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            tar = tarfile.open(fileobj=response, mode="r|gz")
+            tar_extraction_path = os.path.join(temp_dir, tar.firstmember.name)
+
+            tar.extractall(path=temp_dir)
+
+            # If already exist, remove first
+            if (os.path.isdir(destination_dir)):
+                shutil.rmtree(destination_dir)
+
+            # Move from temp folder to destination folder
+            shutil.move(tar_extraction_path, destination_dir)
+
+download_github_repo(org_name, repo_name, destination_dir)