From c99eaf2b2d9f7b70df550b2918bd66b711e41c3f Mon Sep 17 00:00:00 2001 From: Johannes Meyer Date: Thu, 27 Jan 2022 14:11:08 +0100 Subject: [PATCH 1/3] Add parse_template.py --- parse_template.py | 100 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100755 parse_template.py diff --git a/parse_template.py b/parse_template.py new file mode 100755 index 0000000..b7f0711 --- /dev/null +++ b/parse_template.py @@ -0,0 +1,100 @@ +#!/usr/bin/env python3 + +import os +import sys +import json +import argparse + +from jinja2 import Environment, FileSystemLoader, select_autoescape + + +def parse_args(): + parser = argparse.ArgumentParser( + prog='parse_template', + description='a jinja template parser', + add_help=False + ) + + parser.add_argument( + '-h', '--help', + action='help', + help='display help message', + ) + + parser.add_argument( + '-D', '--define', + action='append', + nargs=2, + type=str, + metavar=('key', 'value'), + help='define data with key-value pairs', + ) + + parser.add_argument( + '-o', '--output', + nargs='?', + type=str, + metavar='file', + help='output file or "-" for stdout', + ) + + parser.add_argument( + 'docdir', + type=str, + metavar='docdir', + help='Full documentation directory path', + ) + + parser.add_argument( + 'template', + type=str, + metavar='template', + help='template file path relative to docdir', + ) + + return parser.parse_args() + + +def parse_value(value): + try: + return json.loads(value) + except ValueError: + return value + + +def main(): + args = parse_args() + + doc_dir = args.docdir + template_path = args.template + output = args.output or os.path.join(doc_dir, template_path) + data = {k: parse_value(v) for k, v in args.define or []} + + env = Environment( + loader=FileSystemLoader(doc_dir), + autoescape=False, + block_start_string='', + variable_start_string='', + comment_start_string='', + auto_reload=True, + trim_blocks=True, + lstrip_blocks=True + ) + template = env.get_template(template_path) + + if output == '-': + print(template.render(**data)) + else: + fout = open(output, 'w') + try: + fout.write(template.render(**data)) + finally: + fout.close() + + +if __name__ == '__main__': + main() + From e0385205cd85bdcb8506725550e44bc4f7f51e53 Mon Sep 17 00:00:00 2001 From: Johannes Meyer Date: Thu, 27 Jan 2022 14:11:20 +0100 Subject: [PATCH 2/3] build-docs.rb: Parse templates Templates are files inside a directory which has the same name as a root file plus the `.d` extension. The root file itself then is omitted in the index. --- build-docs.rb | 41 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/build-docs.rb b/build-docs.rb index f17bb55..880fc74 100755 --- a/build-docs.rb +++ b/build-docs.rb @@ -82,19 +82,58 @@ def build_page_index(full_docs_dir, project_docs_dir) next if !file.match(/.*(\d+)-(.*)$/) filepath = file.gsub(full_docs_dir + '/', project_docs_dir + '/') - filename = filepath.match(/.*(\d+)-(.*)$/) + filename = filepath.match(/.*?(\d+)-(.*?)(\.d)?$/) if(File.directory?("#{file}")) subdirectory = [] nav_item = titleize(filename[2]) unless File.symlink?(filepath) + is_template_dir = !filename[3].nil? Dir.glob("#{file}/*.md", File::FNM_CASEFOLD).sort.each do |subfile| subfile_path = subfile.gsub(full_docs_dir + '/', project_docs_dir + '/') subfile_name = subfile.match(/.*(\d+)-(.*)$/) + + if(is_template_dir) + %x(./parse_template.py -D icingaDocs true #{full_docs_dir} #{subfile_path.gsub(/^doc\//, '')}) + + content = File.read(subfile) + # Adjust self references + content = content.gsub(/\[(.*)\]\(#{filename[1]}-#{Regexp.quote(filename[2])}(.*)\)/, '[\1](\2)') + # Adjust external references + content = content.gsub(/\[(.*)\]\((?!http|#)(.*)\)/, '[\1](../\2)') + File.write(subfile, content) + + # Adjust path, the directory will be renamed soon + subdir_name = File.basename(file) + subfile_path = subfile_path.gsub(subdir_name, subdir_name.gsub(/\.md.d$/, '')) + end header = titleize(subfile_name[2]) unless File.symlink?(subfile) subdirectory.push(header => subfile_path) if header end + + if(is_template_dir) + template_path = filepath.gsub(/\.d$/, '') + if(pages.include?(nav_item => template_path)) + pages.delete_at(pages.find_index(nav_item => template_path)) + end + + # Rename template directory to mimic template references + newTemplateDirPath = file.gsub(/\.md.d$/, '') + File.rename(file, newTemplateDirPath) + + # Attempt to create a index file + index_content = %x(./parse_template.py -o - -D index true #{full_docs_dir} #{template_path.gsub(/^doc\//, '')}) + if(!index_content.empty?) + # Adjust self references + index_content = index_content.gsub(/\[(.*)\]\(#{filename[1]}-#{Regexp.quote(filename[2])}(.*)\)/, '[\1](\2)') + # Adjust external references + index_content = index_content.gsub(/\[(.*)\]\((?!http|#)(.*)\)/, '[\1](../\2)') + + File.write(newTemplateDirPath + '/index.md', index_content) + subdirectory.unshift(filepath.gsub(/.md.d$/, '') + '/index.md') + end + end pages.push(nav_item => subdirectory) if nav_item else From 5ea5f3c525dfc01ab12c42afba0f9be720cd6b18 Mon Sep 17 00:00:00 2001 From: Johannes Meyer Date: Fri, 28 Jan 2022 14:27:30 +0100 Subject: [PATCH 3/3] mkdocs.yml: Include feature `navigation.indexes` --- mkdocs.template.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.template.yml b/mkdocs.template.yml index 23842e6..5f71acf 100644 --- a/mkdocs.template.yml +++ b/mkdocs.template.yml @@ -8,6 +8,7 @@ theme: logo: fontawesome/solid/book features: - navigation.instant + - navigation.indexes site_dir: 'html' extra: social: