mirror of
https://github.com/mikecarper/MeshCore.git
synced 2026-10-18 03:49:58 +00:00
mikecarper
4bbd613417
Point both stable providers and runtime controls to the validated v1.17.1.9-halo-keymind-cascade-dev-88c85108 family. Record completed package validation while retaining hardware coverage limitations. Give all documentation source pages their exact hosted links and mount the telemetry form only in the browser. Verify current combined Full and nRF52 Full/Reduced catalog fixtures.
171 lines
7.4 KiB
Python
171 lines
7.4 KiB
Python
#!/usr/bin/env python3
|
|
"""Keep source-visible links aligned with the pages MkDocs actually publishes."""
|
|
|
|
import argparse
|
|
import hashlib
|
|
import html
|
|
import json
|
|
from pathlib import Path
|
|
import re
|
|
import shutil
|
|
from urllib.parse import urljoin, urlsplit
|
|
|
|
HOSTED_BASE = 'https://mikecarper.github.io/MeshCore/'
|
|
BEGIN = '<!-- meshcore-hosted-doc-link:start -->'
|
|
END = '<!-- meshcore-hosted-doc-link:end -->'
|
|
SCRIPT = ' - _javascript/hosted_doc_links.js?v=20261007-1\n'
|
|
SUPPORT_FILES = (
|
|
'scripts/update_hosted_doc_links.py',
|
|
'docs/_javascript/hosted_doc_links.js',
|
|
'test/test_hosted_doc_links.py',
|
|
'test/test_hosted_doc_links.js',
|
|
)
|
|
WORKFLOW_JOB = '''
|
|
hosted-doc-links:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
- uses: actions/setup-python@v6
|
|
with:
|
|
python-version: '3.13'
|
|
- name: Install the documentation renderer
|
|
run: python3 -m pip install mkdocs==1.6.1 mkdocs-material==9.7.7
|
|
- name: Verify source links and published page routes
|
|
run: python3 -B test/test_hosted_doc_links.py -v
|
|
- name: Verify hosted-link visibility and navigation
|
|
run: node test/test_hosted_doc_links.js
|
|
'''
|
|
|
|
|
|
def routes(repo_root):
|
|
"""Use MkDocs' own URL mapping, including non-navigation historical pages."""
|
|
from mkdocs.config import load_config
|
|
from mkdocs.structure.files import get_files
|
|
config = load_config(str(repo_root / 'mkdocs.yml'))
|
|
documents = []
|
|
for file in get_files(config):
|
|
if not file.is_documentation_page() or not file.inclusion.is_included():
|
|
continue
|
|
url = urljoin(HOSTED_BASE, file.url)
|
|
parsed = urlsplit(url)
|
|
if (parsed.scheme != 'https' or parsed.netloc != 'mikecarper.github.io'
|
|
or not parsed.path.startswith('/MeshCore/')):
|
|
raise ValueError('MkDocs page URL escaped the hosted documentation site')
|
|
path = Path(file.abs_src_path)
|
|
if path.is_symlink() or not path.resolve().is_relative_to(Path(config.docs_dir).resolve()):
|
|
raise ValueError('Unsafe documentation source path')
|
|
documents.append({'source': file.src_uri, 'url': url, 'path': path})
|
|
if not documents:
|
|
raise ValueError('MkDocs did not discover any documentation pages')
|
|
return sorted(documents, key=lambda row: row['source'])
|
|
|
|
|
|
def split_frontmatter(text):
|
|
"""Keep an optional BOM and YAML metadata before the source-visible banner."""
|
|
prefix = '\ufeff' if text.startswith('\ufeff') else ''
|
|
body = text[len(prefix):]
|
|
if not re.match(r'\A---(?:\r\n|\n)', body):
|
|
return prefix, body
|
|
lines = body.splitlines(keepends=True)
|
|
for index in range(1, len(lines)):
|
|
if lines[index].rstrip('\r\n') in ('---', '...'):
|
|
return prefix + ''.join(lines[:index + 1]), ''.join(lines[index + 1:])
|
|
raise ValueError('Unterminated documentation frontmatter')
|
|
|
|
|
|
def strip_banner(body):
|
|
if BEGIN not in body and END not in body:
|
|
return body
|
|
if body.count(BEGIN) != 1 or body.count(END) != 1 or not body.startswith(BEGIN + '\n'):
|
|
raise ValueError('Hosted documentation banner is duplicated or misplaced')
|
|
ending = body.find(END) + len(END)
|
|
if body[ending:ending + 2] != '\n\n':
|
|
raise ValueError('Hosted documentation banner delimiter is incomplete')
|
|
return body[ending + 2:]
|
|
|
|
|
|
def with_banner(text, url):
|
|
prefix, body = split_frontmatter(text)
|
|
original = strip_banner(body)
|
|
banner = (BEGIN + '\n<p class="meshcore-hosted-doc-link"><a href="'
|
|
+ html.escape(url, quote=True)
|
|
+ '">View this page on MeshCore Docs</a>.</p>\n' + END + '\n\n')
|
|
return prefix + banner + original
|
|
|
|
|
|
def document_body(text):
|
|
"""Remove only our top banner, leaving the document's original bytes intact."""
|
|
prefix, body = split_frontmatter(text)
|
|
return prefix + strip_banner(body)
|
|
|
|
|
|
def transform(repo_root, *, apply=False):
|
|
rows = []
|
|
for document in routes(repo_root):
|
|
path = document['path']
|
|
before = path.read_bytes()
|
|
text = before.decode('utf-8')
|
|
after = with_banner(text, document['url']).encode('utf-8')
|
|
if document_body(text).encode('utf-8') != document_body(after.decode('utf-8')).encode('utf-8'):
|
|
raise ValueError('A document body changed while adding its hosted link')
|
|
if apply and before != after:
|
|
path.write_bytes(after)
|
|
rows.append({'source': document['source'], 'url': document['url'],
|
|
'already_current': before == after,
|
|
'body_sha256': hashlib.sha256(document_body(text).encode('utf-8')).hexdigest(),
|
|
'document_sha256': hashlib.sha256(after).hexdigest()})
|
|
return {'schema': 'meshcore.docs.hosted-page-links.v1', 'hosted_base': HOSTED_BASE,
|
|
'page_count': len(rows), 'applied': apply, 'pages': rows}
|
|
|
|
|
|
def install_hooks(repo_root):
|
|
"""Add only our script/job; preserve other agents' config and workflow edits."""
|
|
source_root = Path(__file__).resolve().parents[1]
|
|
for name in SUPPORT_FILES:
|
|
source, destination = source_root / name, repo_root / name
|
|
if source.resolve() == destination.resolve():
|
|
continue
|
|
if destination.exists() and destination.read_bytes() != source.read_bytes():
|
|
raise ValueError('Refusing to replace a different hosted-link support file: ' + name)
|
|
destination.parent.mkdir(parents=True, exist_ok=True)
|
|
shutil.copyfile(source, destination)
|
|
config_path = repo_root / 'mkdocs.yml'
|
|
config = config_path.read_text(encoding='utf-8')
|
|
if config.count('extra_javascript:\n') != 1:
|
|
raise ValueError('Expected one MkDocs JavaScript section')
|
|
existing = re.findall(r'^ - _javascript/hosted_doc_links\.js[^\n]*\n', config, re.MULTILINE)
|
|
if len(existing) > 1 or existing and existing[0] != SCRIPT:
|
|
raise ValueError('Unexpected hosted-link JavaScript registration')
|
|
if not existing:
|
|
config_path.write_text(config.replace('extra_javascript:\n', 'extra_javascript:\n' + SCRIPT),
|
|
encoding='utf-8')
|
|
workflow_path = repo_root / '.github/workflows/run-unit-tests.yml'
|
|
workflow = workflow_path.read_text(encoding='utf-8')
|
|
if re.search(r'^ hosted-doc-links:', workflow, re.MULTILINE):
|
|
if workflow.count(WORKFLOW_JOB.strip('\n')) != 1:
|
|
raise ValueError('An unexpected hosted-link workflow job already exists')
|
|
else:
|
|
workflow_path.write_text(workflow.rstrip('\n') + '\n' + WORKFLOW_JOB, encoding='utf-8')
|
|
|
|
|
|
def main():
|
|
parser = argparse.ArgumentParser(description=__doc__)
|
|
parser.add_argument('--root', type=Path, default=Path(__file__).resolve().parents[1])
|
|
parser.add_argument('--apply', action='store_true', help='Update page banners and add their shared script/test job')
|
|
parser.add_argument('--manifest', type=Path)
|
|
args = parser.parse_args()
|
|
root = args.root.resolve()
|
|
if args.apply:
|
|
install_hooks(root)
|
|
manifest = transform(root, apply=args.apply)
|
|
if args.manifest:
|
|
args.manifest.write_text(json.dumps(manifest, sort_keys=True, indent=2) + '\n', encoding='ascii')
|
|
pending = sum(not row['already_current'] for row in manifest['pages'])
|
|
print(json.dumps({'pages': manifest['page_count'], 'updated' if args.apply else 'pending': pending}))
|
|
if not args.apply and pending:
|
|
parser.exit(1, 'Hosted documentation links differ; run this script with --apply.\n')
|
|
|
|
|
|
if __name__ == '__main__':
|
|
main()
|