From 23cf63658e284776e7d7a2017f646129fd8778fc Mon Sep 17 00:00:00 2001 From: Gerwin Klein Date: Fri, 20 Jun 2025 11:05:11 +1000 Subject: [PATCH] preprocess microkit tutorial for Jekyll - process {{#include ... }} directives - replace {{#tab ... }} directives with Jekyll includes Signed-off-by: Gerwin Klein --- .gitignore | 1 + Makefile | 14 +++++- _includes/endtab.html | 0 _includes/endtabs.html | 0 _includes/tab.html | 0 _includes/tabs.html | 0 _processed/README.md | 16 +++++++ _scripts/process-mdbook.py | 68 +++++++++++++++++++++++++++ projects/microkit/tutorial/end.md | 2 +- projects/microkit/tutorial/part0.md | 2 +- projects/microkit/tutorial/part1.md | 2 +- projects/microkit/tutorial/part2.md | 2 +- projects/microkit/tutorial/part3.md | 2 +- projects/microkit/tutorial/part4.md | 2 +- projects/microkit/tutorial/rpi3b.md | 2 +- projects/microkit/tutorial/welcome.md | 2 +- 16 files changed, 106 insertions(+), 9 deletions(-) create mode 100644 _includes/endtab.html create mode 100644 _includes/endtabs.html create mode 100644 _includes/tab.html create mode 100644 _includes/tabs.html create mode 100644 _processed/README.md create mode 100755 _scripts/process-mdbook.py diff --git a/.gitignore b/.gitignore index 7aab3a49ae..3de92832bc 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ projects/virtualization/docs/api/ .jekyll-cache/ vendor/ node_modules/ +_processed/microkit-tutorial/ diff --git a/Makefile b/Makefile index abac771a81..6cd0bc7f63 100644 --- a/Makefile +++ b/Makefile @@ -57,6 +57,18 @@ _repos/tutes/%.md: _repos/sel4proj/sel4-tutorials/tutorials/% _repos/tutes TUTORIALS:= $(filter-out index.md get-the-tutorials.md how-to.md pathways.md setting-up.md,$(notdir $(wildcard Tutorials/*.md))) tutorials: ${TUTORIALS:%=_repos/tutes/%} +PROCESS_MDBOOK = _scripts/process-mdbook.py +MICROKIT_TUT_DST = _processed/microkit-tutorial +MICROKIT_TUT_SRC = _repos/au-ts/microkit_tutorial/website/src +MICROKIT_TUT_SRC_FILES = $(wildcard $(MICROKIT_TUT_SRC)/*.md) +MICROKIT_TUT_DST_FILES = $(patsubst $(MICROKIT_TUT_SRC)/%, $(MICROKIT_TUT_DST)/%, $(MICROKIT_TUT_SRC_FILES)) + +$(MICROKIT_TUT_DST)/%.md: $(MICROKIT_TUT_SRC)/%.md + @echo "$< ==> $@" + @$(PROCESS_MDBOOK) $< $(dir $@) + +microkit-tutorial: $(MICROKIT_TUT_DST_FILES) + _generate_api_pages: $(REPOSITORIES) $(MAKE) markdown -C _repos/sel4/sel4/manual @@ -93,7 +105,7 @@ docker_build: serve: build JEKYLL_ENV=$(JEKYLL_ENV) bundle exec jekyll serve -build: generate_api ruby_deps $(REPOSITORIES) +build: generate_api ruby_deps microkit-tutorial $(REPOSITORIES) $(MAKE) tutorials ifeq ($(JEKYLL_ENV),production) $(MAKE) generate_data_files diff --git a/_includes/endtab.html b/_includes/endtab.html new file mode 100644 index 0000000000..e69de29bb2 diff --git a/_includes/endtabs.html b/_includes/endtabs.html new file mode 100644 index 0000000000..e69de29bb2 diff --git a/_includes/tab.html b/_includes/tab.html new file mode 100644 index 0000000000..e69de29bb2 diff --git a/_includes/tabs.html b/_includes/tabs.html new file mode 100644 index 0000000000..e69de29bb2 diff --git a/_processed/README.md b/_processed/README.md new file mode 100644 index 0000000000..4a179bdf58 --- /dev/null +++ b/_processed/README.md @@ -0,0 +1,16 @@ + + +# Target directory for generated files + +This is target directory directory for generated/processed files based on data +or input taken from other repositories in `../_repos`. + +- `tutes/` contains processed md files from the sel4-tutorials repository + +- `microkit-tutorial/` contains processed md files from the microkit-tutorial + repo. + +These files will then be included via Jekyll/Liquid tags elsewhere in the site. diff --git a/_scripts/process-mdbook.py b/_scripts/process-mdbook.py new file mode 100755 index 0000000000..a4ada323c8 --- /dev/null +++ b/_scripts/process-mdbook.py @@ -0,0 +1,68 @@ +#! /usr/bin/env python3 + +# Copyright 2025 Proofcraft Pty Ltd +# SPDX-License-Identifier: BSD-2-Clause + +# Process mdbook .md files to +# - execute `{{#include "path/to/file.md"}}` directives +# - convert tab directives Jekyll includes used in the docsite + +import os +import re +import argparse + +def inclusion_content(input_path, match): + include_path = match.group(1) + start_line = match.group(2) + end_line = match.group(3) + + full_path = os.path.join(input_path, include_path) + if os.path.exists(full_path): + with open(full_path, 'r', encoding='utf-8') as inc_file: + lines = inc_file.read().splitlines() + if start_line is None: + start_line = 1 + if end_line is None: + end_line = len(lines) + else: + end_line = int(end_line) + # Return the specified lines as a string + return '\n'.join(lines[int(start_line)-1:end_line]) + else: + print(f'Include file {include_path} not found in {input_path}') + return f'' + +def process_mdbook(input_file, output_dir): + if not os.path.exists(output_dir): + os.makedirs(output_dir) + + # Read entire input file + with open(input_file, 'r', encoding='utf-8') as f: + content = f.read() + + # Process include directives with line numbers + include_pattern = re.compile(r'{{#include[ ]*([^ :]+)(?::(\d+):(\d+))?[ ]*}}') + input_path = os.path.dirname(input_file) + content = re.sub(include_pattern, lambda match: inclusion_content(input_path, match), content) + + # Convert tab directives to Jekyll includes + # {{#tabs }}, {{#endtabs }}, {{#endtab }} + pat = re.compile(r'{{#([a-z]*tabs?)[ ]*}}') + content = re.sub(pat, r'{% include \1.html %}', content) + + # "{{#tab name="Linux" }}" + pat = re.compile(r'{{#tab name="([^"]+)"[ ]*}}') + content = re.sub(pat, r'{% include tab.html title="\1" %}', content) + + # Write processed content + output_file = os.path.join(output_dir, os.path.basename(input_file)) + with open(output_file, 'w', encoding='utf-8') as f: + f.write(content) + +if __name__ == "__main__": + parser = argparse.ArgumentParser(description='Process mdbook .md files for includes and tabs.') + parser.add_argument('input_file', help='Path to the input .md file') + parser.add_argument('output_dir', help='Directory to save the processed output') + + args = parser.parse_args() + process_mdbook(args.input_file, args.output_dir) diff --git a/projects/microkit/tutorial/end.md b/projects/microkit/tutorial/end.md index 4c8be023d7..75230e7196 100644 --- a/projects/microkit/tutorial/end.md +++ b/projects/microkit/tutorial/end.md @@ -5,4 +5,4 @@ SPDX-FileCopyrightText: 2025 Ivan Velickovic --- {% include include_external_markdown.md - file="_repos/au-ts/microkit_tutorial/website/src/end.md" %} + file="_processed/microkit-tutorial/end.md" %} diff --git a/projects/microkit/tutorial/part0.md b/projects/microkit/tutorial/part0.md index 89ef011480..20fb09a0a1 100644 --- a/projects/microkit/tutorial/part0.md +++ b/projects/microkit/tutorial/part0.md @@ -5,4 +5,4 @@ SPDX-FileCopyrightText: 2025 Ivan Velickovic --- {% include include_external_markdown.md - file="_repos/au-ts/microkit_tutorial/website/src/part0.md" %} + file="_processed/microkit-tutorial/part0.md" %} diff --git a/projects/microkit/tutorial/part1.md b/projects/microkit/tutorial/part1.md index 37e2f126e3..4e3dc3f072 100644 --- a/projects/microkit/tutorial/part1.md +++ b/projects/microkit/tutorial/part1.md @@ -5,4 +5,4 @@ SPDX-FileCopyrightText: 2025 Ivan Velickovic --- {% include include_external_markdown.md - file="_repos/au-ts/microkit_tutorial/website/src/part1.md" %} + file="_processed/microkit-tutorial/part1.md" %} diff --git a/projects/microkit/tutorial/part2.md b/projects/microkit/tutorial/part2.md index 8c1cdf9df1..a807db8837 100644 --- a/projects/microkit/tutorial/part2.md +++ b/projects/microkit/tutorial/part2.md @@ -5,4 +5,4 @@ SPDX-FileCopyrightText: 2025 Ivan Velickovic --- {% include include_external_markdown.md - file="_repos/au-ts/microkit_tutorial/website/src/part2.md" %} + file="_processed/microkit-tutorial/part2.md" %} diff --git a/projects/microkit/tutorial/part3.md b/projects/microkit/tutorial/part3.md index 64433c5ca7..db6625fa98 100644 --- a/projects/microkit/tutorial/part3.md +++ b/projects/microkit/tutorial/part3.md @@ -5,4 +5,4 @@ SPDX-FileCopyrightText: 2025 Ivan Velickovic --- {% include include_external_markdown.md - file="_repos/au-ts/microkit_tutorial/website/src/part3.md" %} + file="_processed/microkit-tutorial/part3.md" %} diff --git a/projects/microkit/tutorial/part4.md b/projects/microkit/tutorial/part4.md index c7e27a174c..cfb047ff44 100644 --- a/projects/microkit/tutorial/part4.md +++ b/projects/microkit/tutorial/part4.md @@ -5,4 +5,4 @@ SPDX-FileCopyrightText: 2025 Ivan Velickovic --- {% include include_external_markdown.md - file="_repos/au-ts/microkit_tutorial/website/src/part4.md" %} + file="_processed/microkit-tutorial/part4.md" %} diff --git a/projects/microkit/tutorial/rpi3b.md b/projects/microkit/tutorial/rpi3b.md index 8e41544d72..1173b51912 100644 --- a/projects/microkit/tutorial/rpi3b.md +++ b/projects/microkit/tutorial/rpi3b.md @@ -5,4 +5,4 @@ SPDX-FileCopyrightText: 2025 Ivan Velickovic --- {% include include_external_markdown.md - file="_repos/au-ts/microkit_tutorial/website/src/rpi3b.md" %} + file="_processed/microkit-tutorial/rpi3b.md" %} diff --git a/projects/microkit/tutorial/welcome.md b/projects/microkit/tutorial/welcome.md index 1dbc925926..897b98b912 100644 --- a/projects/microkit/tutorial/welcome.md +++ b/projects/microkit/tutorial/welcome.md @@ -5,4 +5,4 @@ SPDX-FileCopyrightText: 2025 Ivan Velickovic --- {% include include_external_markdown.md - file="_repos/au-ts/microkit_tutorial/website/src/welcome.md" %} + file="_processed/microkit-tutorial/welcome.md" %}