Skip to content

Commit 14750e8

Browse files
zlovattzlovatt
authored
Merge pull request #48 from docsforadobe/change/common-config
Update repo to use common org-wide components
2 parents 6805b42 + 3da5f80 commit 14750e8

19 files changed

+324
-70
lines changed

‎.github/workflows/ci.yml

+5-6
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ jobs:
2222
- uses: actions/setup-python@v5
2323
with:
2424
python-version: 3.x
25+
2526
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
2627

2728
- uses: actions/cache@v4
@@ -30,10 +31,8 @@ jobs:
3031
path: .cache
3132
restore-keys: |
3233
mkdocs-material-
33-
- run: >
34-
pip install
35-
markdown_grid_tables
36-
mkdocs-git-revision-date-localized-plugin
37-
mkdocs-material
38-
mkdocs-print-site-plugin
34+
35+
- name: Install Python dependencies
36+
uses: py-actions/py-dependency-install@v4
37+
3938
- run: mkdocs gh-deploy --force

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,6 @@
22
*.sublime-workspace
33
.DS_Store
44
.vscode/
5+
__pycache__/
56
site/
67
venv/

‎docs/_global/.gitignore

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
*.sublime-project
2+
*.sublime-workspace
3+
.DS_Store
4+
.vscode/
5+
__pycache__/
6+
site/
7+
venv/

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

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
/* Set light & dark mode syntax highlight */
2+
3+
@media screen {
4+
/* Light mode */
5+
[data-md-color-scheme="default"] {
6+
--md-code-fg-color: #36464e;
7+
--md-code-bg-color: #f5f5f5;
8+
--md-code-hl-color: #4287ff;
9+
10+
--md-code-hl-constant-color: #6e59d9;
11+
--md-code-hl-function-color: #a846b9;
12+
--md-code-hl-keyword-color: #3f6ec6;
13+
--md-code-hl-number-color: #d52a2a;
14+
--md-code-hl-special-color: #db1457;
15+
--md-code-hl-string-color: #1c7d4d;
16+
--md-code-hl-comment-color: var(--md-default-fg-color--light);
17+
--md-code-hl-generic-color: var(--md-default-fg-color--light);
18+
--md-code-hl-name-color: var(--md-code-fg-color);
19+
--md-code-hl-operator-color: var(--md-default-fg-color--light);
20+
--md-code-hl-punctuation-color: var(--md-default-fg-color--light);
21+
--md-code-hl-variable-color: var(--md-default-fg-color--light);
22+
}
23+
24+
/* Dark mode */
25+
[data-md-color-scheme="slate"] {
26+
--md-code-bg-color: #272a35;
27+
--md-code-fg-color: #d5d8e2d1;
28+
--md-code-hl-color: #2977ff;
29+
30+
--md-code-hl-constant-color: #9383e2;
31+
--md-code-hl-function-color: #c973d9;
32+
--md-code-hl-keyword-color: #6791e0;
33+
--md-code-hl-number-color: #e6695b;
34+
--md-code-hl-special-color: #f06090;
35+
--md-code-hl-string-color: #2fb170;
36+
--md-code-hl-comment-color: var(--md-default-fg-color--light);
37+
--md-code-hl-generic-color: var(--md-default-fg-color--light);
38+
--md-code-hl-name-color: var(--md-code-fg-color);
39+
--md-code-hl-operator-color: var(--md-default-fg-color--light);
40+
--md-code-hl-punctuation-color: var(--md-default-fg-color--light);
41+
--md-code-hl-variable-color: var(--md-default-fg-color--light);
42+
}
43+
}

‎docs/_global/css/global.css

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

‎docs/_global/hooks/merge_inherited_config.py

+119
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Handles merging mkdocs config in a way the native inheritance feature doesn't quite cover
2+
#
3+
# This relies on a key in "extra.overrides"
4+
# Valid keys are `custom_dir: str` and `hooks: [-path/to.py, -path/to.py]`, e.g.
5+
#
6+
# ```yml
7+
# extra:
8+
# overrides:
9+
# custom_dir: overrides
10+
# extra_css:
11+
# - docs/_global/css/global.css
12+
# - docs/_global/css/global-syntax-highlight.css
13+
# extra_javascript:
14+
# - docs/_global/js/global.js
15+
# hooks:
16+
# - hooks/local_override.py
17+
# - hooks/local_override2.py
18+
# not_in_nav:
19+
# - gitignore_style/path/to/exclude
20+
# theme_features:
21+
# - theme.feature1
22+
# - theme.feature2
23+
# ```
24+
25+
import os
26+
27+
from pathspec.gitignore import GitIgnoreSpec
28+
29+
import mkdocs
30+
from mkdocs.config.defaults import MkDocsConfig
31+
from mkdocs.config.config_options import (File, FilesystemObject, Hooks, ListOfItems, PathSpec)
32+
from mkdocs.structure.files import (File as FileStructure, Files)
33+
34+
# Load any local files into mkdocs
35+
def append_local_files(files: Files, config: MkDocsConfig, local_files: list[str]):
36+
for local_file_path in local_files:
37+
local_file = FileStructure(
38+
path= local_file_path,
39+
src_dir=config["docs_dir"] + "/../",
40+
dest_dir=config["site_dir"],
41+
use_directory_urls=False,
42+
)
43+
44+
files.append(local_file)
45+
46+
# Load any override hooks
47+
def merge_local_hooks(config: MkDocsConfig, hooks: list[str]):
48+
try:
49+
paths = ListOfItems(File(exists=True)).validate(hooks)
50+
except Exception as e:
51+
raise e
52+
53+
for name, path in zip(hooks, paths):
54+
config.plugins[name] = Hooks._load_hook(mkdocs, name, path)
55+
56+
# Handle multiple "not in nav" entries
57+
# These are of a pathspec.gitignore.GitIgnoreSpec format and need to be converted to a multiline string
58+
def merge_local_not_in_nav(config: MkDocsConfig, not_in_nav: list[GitIgnoreSpec]):
59+
nav_str = "\n".join(not_in_nav)
60+
config["not_in_nav"] += PathSpec().run_validation(nav_str)
61+
62+
# Add additional theme_override folder
63+
def merge_local_theme_override(config: MkDocsConfig, custom_dir: str):
64+
try:
65+
local_override_path = FilesystemObject(exists=True).validate(custom_dir)
66+
except Exception as e:
67+
raise e
68+
69+
config.theme.dirs.insert(1, local_override_path)
70+
71+
# Load any override theme features
72+
def merge_local_theme_features(config: MkDocsConfig, theme_features: list[str]):
73+
for local_feature in theme_features:
74+
config.theme["features"].append(local_feature)
75+
76+
77+
78+
##### MkDocs Event Hooks
79+
80+
def on_files(files: Files, config: MkDocsConfig):
81+
if "overrides" in config.extra:
82+
extra_overrides = config.extra["overrides"]
83+
84+
if "extra_css" in extra_overrides:
85+
extra_css = extra_overrides["extra_css"]
86+
append_local_files(files, config, extra_css)
87+
88+
if "extra_javascript" in extra_overrides:
89+
extra_javascript = extra_overrides["extra_javascript"]
90+
append_local_files(files, config, extra_javascript)
91+
92+
def on_config(config: MkDocsConfig):
93+
if "overrides" in config.extra:
94+
extra_overrides = config.extra["overrides"]
95+
96+
# Keep Hooks first
97+
if "hooks" in extra_overrides:
98+
hooks = extra_overrides["hooks"]
99+
merge_local_hooks(config, hooks)
100+
101+
if "custom_dir" in extra_overrides:
102+
custom_dir = extra_overrides["custom_dir"]
103+
merge_local_theme_override(config, custom_dir)
104+
105+
if "extra_css" in extra_overrides:
106+
extra_css = extra_overrides["extra_css"]
107+
config.extra_css.extend(extra_css)
108+
109+
if "extra_javascript" in extra_overrides:
110+
extra_javascript = extra_overrides["extra_javascript"]
111+
config.extra_javascript.extend(extra_javascript)
112+
113+
if "not_in_nav" in extra_overrides:
114+
not_in_nav = extra_overrides["not_in_nav"]
115+
merge_local_not_in_nav(config, not_in_nav)
116+
117+
if "theme_features" in extra_overrides:
118+
theme_features = extra_overrides["theme_features"]
119+
merge_local_theme_features(config, theme_features)

‎docs/_global/js/global.js

Whitespace-only changes.

‎docs/_global/mkdocs.yml

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Shared config for all repos
2+
copyright: All content is copyright Adobe Systems Incorporated.
3+
4+
extra:
5+
homepage: https://docsforadobe.dev
6+
7+
# Using overrides here as we can't inherit "extra_css"
8+
overrides:
9+
extra_css:
10+
- docs/_global/css/global.css
11+
- docs/_global/css/global-syntax-highlight.css
12+
extra_javascript:
13+
- docs/_global/js/global.js
14+
15+
hooks:
16+
- docs/_global/hooks/merge_inherited_config.py
17+
18+
markdown_extensions:
19+
admonition: {}
20+
markdown_grid_tables: {}
21+
md_in_html: {}
22+
pymdownx.details: {}
23+
pymdownx.superfences: {}
24+
pymdownx.tabbed:
25+
alternate_style: true
26+
pymdownx.tasklist:
27+
custom_checkbox: true
28+
toc:
29+
title: Page Contents
30+
permalink: true
31+
toc_depth: 3
32+
33+
not_in_nav: |
34+
_global
35+
36+
plugins:
37+
git-revision-date-localized: {}
38+
search:
39+
separator: '[\s\-,\.:!=\[\]()"/]+'
40+
41+
# Note: print-site must be last!
42+
print-site:
43+
add_cover_page: true
44+
add_print_site_banner: true
45+
cover_page_template: "docs/_global/overrides/templates/print_site_cover_page.tpl"
46+
print_page_title: "Offline Docs"
47+
print_site_banner_template: "docs/_global/overrides/templates/print_site_banner.tpl"
48+
49+
theme:
50+
name: material
51+
custom_dir: docs/_global/overrides
52+
features:
53+
- announce.dismiss
54+
- content.action.edit
55+
- content.action.view
56+
- search.highlight
57+
- search.suggest
58+
- toc.follow
59+
palette:
60+
# Palette toggle for dark mode
61+
- media: "(prefers-color-scheme: dark)"
62+
primary: black
63+
scheme: slate
64+
toggle:
65+
icon: material/brightness-4
66+
name: Switch to light mode
67+
68+
# Palette toggle for light mode
69+
- media: "(prefers-color-scheme: light)"
70+
primary: white
71+
scheme: default
72+
toggle:
73+
icon: material/brightness-7
74+
name: Switch to dark mode

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

File renamed without changes.

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{% extends "base.html" %}
22

33
{% block announce %}
4-
Welcome to the new scripting guide!
4+
Welcome to the new docsforadobe guide!
55

66
This is a work in progress.
77

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

File renamed without changes.

‎overrides/partials/toc-item.html renamed to ‎docs/_global/overrides/partials/toc-item.html

File renamed without changes.

‎overrides/templates/print_site_banner.tpl renamed to ‎docs/_global/overrides/templates/print_site_banner.tpl

File renamed without changes.

‎overrides/templates/print_site_cover_page.tpl renamed to ‎docs/_global/overrides/templates/print_site_cover_page.tpl

File renamed without changes.

‎docs/_global/readme.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# docsforadobe.dev MkDocs Config
2+
3+
This repo holds the common components shared between this org's hosted MkDocs documentation projects.
4+
5+
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.
6+
7+
In all cases, each child repo will be able to *override* config items here as needed.
8+
9+
## Updating This Repo
10+
11+
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.

‎docs/_global/requirements.txt

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
markdown_grid_tables
2+
mkdocs
3+
mkdocs-git-revision-date-localized-plugin
4+
mkdocs-material
5+
mkdocs-print-site-plugin

‎docs/_global/scripts/update-common-components.py

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
import os
2+
import shutil
3+
import tarfile
4+
import tempfile
5+
import urllib.request
6+
7+
org_name = "docsforadobe"
8+
repo_name = "docsforadobe-mkdocs-config"
9+
destination_dir = "./docs/_global"
10+
11+
def download_github_repo(org_name, repo_name, destination_dir):
12+
tar_url = f"https://api.github.com/repos/{org_name}/{repo_name}/tarball/main"
13+
14+
response = urllib.request.urlopen(tar_url)
15+
16+
if (response):
17+
with tempfile.TemporaryDirectory() as temp_dir:
18+
tar = tarfile.open(fileobj=response, mode="r|gz")
19+
tar_extraction_path = os.path.join(temp_dir, tar.firstmember.name)
20+
21+
tar.extractall(path=temp_dir)
22+
23+
# If already exist, remove first
24+
if (os.path.isdir(destination_dir)):
25+
shutil.rmtree(destination_dir)
26+
27+
# Move from temp folder to destination folder
28+
shutil.move(tar_extraction_path, destination_dir)
29+
30+
download_github_repo(org_name, repo_name, destination_dir)

0 commit comments

Comments
 (0)