diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..c04ea283 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +# docs output +/docs/ diff --git a/tools/README.md b/tools/README.md index 8c2d4fe9..c1fdea78 100644 --- a/tools/README.md +++ b/tools/README.md @@ -50,6 +50,13 @@ The script expects the JSON file to be located at: - Creates navigation links (table of contents) for all IDs and descriptions. - Generates technical documentation that includes commands, prompts, conditions, author information, and status. - Creates user-focused documentation with simplified instructions. +- Includes custom header, footer and section image: + + ``` + - tools/include/markdown/ID-header.md + - tools/include/markdown/ID-footer.md + - tools/include/images/ID.png + ``` #### Dependencies diff --git a/tools/config-markdown.py b/tools/config-markdown.py index 259caaf5..3c6b39b5 100755 --- a/tools/config-markdown.py +++ b/tools/config-markdown.py @@ -2,8 +2,11 @@ import json import os +import os.path import argparse +from pathlib import Path + # Get the absolute path of the script's directory script_dir = os.path.dirname(os.path.abspath(__file__)) @@ -64,18 +67,39 @@ def create_markdown_technical(item, level=1): return md_content def create_markdown_user(item, level=1): + """Recursively create Markdown content for user documentation from JSON.""" #user_content = f"\n" # if above A link is not working, use below line #user_content += f"{'#' * level} {item['id']}\n" #user_content = f"# {item.get('description', '')}\n" + + # verify if header or footer exists + image_include = Path(os.path.dirname(os.path.abspath(__file__))+'/include/images/'+item['id']+'.png') + header_include = Path(os.path.dirname(os.path.abspath(__file__))+'/include/markdown/'+item['id']+'-header.md') + footer_include = Path(os.path.dirname(os.path.abspath(__file__))+'/include/markdown/'+item['id']+'-footer.md') + user_content = f"{'#' * level} {item.get('description', '')}\n" - + + # include image for section if exists + if image_include.is_file(): + user_content +="\n\n" + with open(image_include, 'r') as file: + user_content += "[!["+ item.get('description', '') + "](images/"+item['id']+".png)](#)\n" + user_content +="\n\n" + + # include markdown header for section if exists + if header_include.is_file(): + user_content +="\n\n" + with open(header_include, 'r') as file: + user_content += f""+file.read().replace('\n', '')+"\n" + user_content +="\n\n" + if 'about' in item and item['about']: user_content += f"{item['about']}\n\n" if 'command' in item: - user_content += f"**Command:** \n~~~\n--cmd {item['id']}\n~~~\n\n" + user_content += f"**Command:** \n~~~\narmbian-config --cmd {item['id']}\n~~~\n\n" if 'author' in item: user_content += f"**Author:** {item['author']}\n\n" @@ -83,6 +107,13 @@ def create_markdown_user(item, level=1): if 'status' in item: user_content += f"**Status:** {item['status']}\n\n" + # include footer for section if exists + if footer_include.is_file(): + user_content +="\n\n" + with open(footer_include, 'r') as file: + user_content += f""+file.read().replace('\n', '')+"\n" + user_content +="\n\n" + user_content += '\n\n***\n\n' # Add extra line for spacing # Recursively add sub-items if they exist diff --git a/tools/include/README.md b/tools/include/README.md new file mode 100644 index 00000000..cd3bd8cc --- /dev/null +++ b/tools/include/README.md @@ -0,0 +1,7 @@ +Images, headers and footers that contains: + +- ID-header.md +- ID-footer.md +- ID.png + +will be automatically embedded into respective parts of the documentation. diff --git a/tools/include/images/DE31.png b/tools/include/images/DE31.png new file mode 100644 index 00000000..8612ea93 Binary files /dev/null and b/tools/include/images/DE31.png differ diff --git a/tools/include/markdown/DE31-footer.md b/tools/include/markdown/DE31-footer.md new file mode 100644 index 00000000..da9d555f --- /dev/null +++ b/tools/include/markdown/DE31-footer.md @@ -0,0 +1,3 @@ +Cinnamon is a Linux desktop that provides advanced innovative features and a traditional user experience. + +The desktop layout is similar to Gnome 2 with underlying technology forked from Gnome Shell. Cinnamon makes users feel at home with an easy-to-use and comfortable desktop experience.